Ask HN: SOAP vs REST - help me understand • Hacker News Board

Ask HN: SOAP vs REST - help me understand

#1

Post by faxman » Sun, Jan 15, 2012, 3:16 PM UTC

My company has been offering a SOAP-based API since around 2002. We recently ran a survey on our site in which a full 25% of visiting developers said that SOAP is a show-stopper for them and that they would prefer REST, even though we provide full code samples in various languages for our SOAP interface.

Ever mindful of our clients' wishes, we've begun designing a REST interface. We've been trying to adopt the best practices of API providers out there, and we're planning to provide client libraries for the most popular languages as well.

This will take us a good few months, designing objects and operations, implementing the service, creating code samples, etc. At the end of this process, a PHP developer, for example, will be able to send a fax through the REST API by using this code:

       SendFax;  
       echo $result;

       ?>

instead of this code:

       Username  = $username;
       $params->Password  = $password;
       $params->FaxNumber = $faxnumber;
       $params->Data      = $texttofax ;
       $params->FileType  = $filetype;
        
       $result = $client->SendCharFax($params);
        
       echo $result->SendCharFaxResult;  
       ?>

which is, effectively, the same. The complexity of interfacing to the API is hidden in a custom library instead of a SOAP library. Which brings me to ask myself "what's the point"? Where does the advantage of having a REST interface come into play?

Re: Ask HN: SOAP vs REST - help me understand

#2

Post by toyg » Sun, Jan 15, 2012, 3:49 PM UTC

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.

Re: Ask HN: SOAP vs REST - help me understand

#3

Post by faxman » Sun, Jan 15, 2012, 4:12 PM UTC

toyg wrote: post #2

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 basi…

No, not trolling.

The vast majority of API providers do provide libraries (of course, none of them "force" you to use them, and nor will we), and this is considered good practice in many places (see for example the recent "Designing Great API Docs" at https://news.ycombinator.com/item?id=3453315).

I understand the purism of doing it the REST way, but if in practice most developers end up using a library which abstracts away REST - that's what prompted my original question.

Re: Ask HN: SOAP vs REST - help me understand

#4

Post by toyg » Sun, Jan 15, 2012, 4:29 PM UTC

faxman wrote: post #3

toyg wrote: post #2

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 basi…

No, not trolling. The vast majority of API providers do provide libraries (of course, none of them "force" you to use them, and nor will we), and this is considered good practice in many places (see for example the recent "Designing Great API Docs" at https://news.ycombinator.com/item?id=3453315 ). I understand the purism of doing it the REST way, but if in practice most developers end up using a library which abstra…

Yeah, a library for a library, there's little difference, I agree; but the main point of REST is exactly the fact that the library is optional, and if necessary it can be entirely bypassed with little effort. With SOAP this is almost invariably impractical or impossible; you'll need a basic SOAP library even for sending "Hello world" back and forth. REST is more human-friendly in many ways.

Somebody could also say REST implementations usually end up passing less data around, because they usually don't require the overhead of compulsory metadata typical of SOAP standards (schemas, "envelopes" etc). This is obviously a trade-off with "exactness", but again most developers are happy to trade speed for metadata they'll rarely use (if ever). It also helps making server-side caching easier.

Re: Ask HN: SOAP vs REST - help me understand

#5

Post by JS_startup » Sun, Jan 15, 2012, 5:22 PM UTC

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.

Re: Ask HN: SOAP vs REST - help me understand

#6

Post by arghnoname » Sun, Jan 15, 2012, 5:52 PM UTC

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?

Re: Ask HN: SOAP vs REST - help me understand

#7

Post by cheald » Sun, Jan 15, 2012, 11:35 PM UTC

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.

Re: Ask HN: SOAP vs REST - help me understand

#8

Post by DougWebb » Mon, Jan 16, 2012, 1:04 AM UTC

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.)

Re: Ask HN: SOAP vs REST - help me understand

#9

Post by faxman » Mon, Jan 16, 2012, 1:33 PM UTC

arghnoname wrote: post #6

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?

Actually, moving to REST requires you to change your head around from a procedural point of view to one dealing in objects and operations, so it won't be a direct mapping of SOAP to REST.

Re: Ask HN: SOAP vs REST - help me understand

#10

Post by faxman » Mon, Jan 16, 2012, 1:35 PM UTC

toyg wrote: post #4

faxman wrote: post #3

Earlier quoted context omitted.

No, not trolling. The vast majority of API providers do provide libraries (of course, none of them "force" you to use them, and nor will we), and this is considered good practice in many places (see for example the recent "Designing Great API Docs" at https://news.ycombinator.com/item?id=3453315 ). I understand the purism of doing it the REST way, but if in practice most developers end up using a library which abstra…

Yeah, a library for a library, there's little difference, I agree; but the main point of REST is exactly the fact that the library is optional, and if necessary it can be entirely bypassed with little effort. With SOAP this is almost invariably impractical or impossible; you'll need a basic SOAP library even for sending "Hello world" back and forth. REST is more human-friendly in many ways. Somebody could also say RE…

OK, thanks. Going back to the drawing board with renewed vigor!