Ask HN: SOAP vs REST - help me understand

I hope you are not trolling.

The difference between REST and SOAP is how you expose your api via HTTP; with a RESTful approach, you should expose clean URLs that will be accessed via http methods expressing their original meaning (i.e. GET will only fetch a resource, not trigger side-effects; creation operations will use POST; etc etc). This usually results in simple interfaces that can be accessed directly with basic http libraries and don't necessarily rely on XML. The point of REST is that any http client will be able to access your API; wrapping libraries like the one you provide are completely optional.

Developers prefer REST for this reason: it's much easier than SOAP (where you invariably have to rely on wrapping libraries you don't understand) and doesn't introduce any dependency on libraries. If you intend on forcing customers to use a wrapping library anyway, then it doesn't really matter what you choose, because you're completely hiding the http layer anyway. Doing it "the REST way" would mean you just document your http interfaces and make the wrapper completely optional, while maintaining simplicity.

The primary appeal of a REST interface is simplicity. You don't need a proprietary library to make sense of it. All you need are a list of resources and in the case of PUT/POST operations, parameters, and the rest is handled by the nature of HTTP. No fancy libraries, no confounded WSDL files, easily-inspected responses. You can consume it using very common libraries and even roll your own with ease.

If you're always providing API access through a proprietary library, it doesn't matter if it's REST, SOAP, custom binary protocols, or whatnot.

If your clients only use your provided libraries then there is no difference between SOAP and REST in this instance as the primary attraction of REST (accessing the methods through HTTP requests) will be abstracted by the library.

So either that 25% wants a RESTful interface because they're going to opt not to use your libraries or because they're conditioned to vote for REST over SOAP.

Two things:

* You're going to have to support your SOAP endpoint anyway, so only maintain libraries for your SOAP endpoint (at least for now). Having a PHP library for SOAP and a PHP library for REST will just confuse people to no end.

* Put up a form on your web site that says "Put your email in to get early access to our REST API" and then see if anyone actually bites.

Just because someone on a survey said they wanted REST instead of SOAP doesn't mean that you have to run off and do it, or that they wouldn't necessarily use the SOAP API if they actually had to solve a problem with your API.

We built some really interesting stuff on SOAP and WS-* in the 2002-2003 era, and it's always fun to see development trends go in circles.

Personally I'd just wrap SoapClient to provide the more succinct interface and provide that to your users. You could probably programmatically generate a draft of this interface, and then manually improve and simplify it if you want. Maybe this is how you are going to implement your REST interface?

It's tough to tell how RESTful your API is when it's wrapped up in a client-side library. One of the ways I evaluate this is to ask: if I'm using a compiled client-side language, and the service api is modified in a backward-compatible way, will I need to recompile my client? With SOAP the answer is often yes because the client-side library generates code that is binary-dependent on the datatypes in the wsdl. That's bad, and one of the huge advantages of a RESTful api is that recompiles aren't needed. Your resource representation can change, so long as the informationn that was there before is still there and can be found using the same expression (eg: an id lookup in an xml document, or by a key in json data.)