HN Explorer

Ask HN: SOAP vs REST - help me understand

7 points by faxman ↗ HN
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:

       <?php

       require('Interfax.php');
       $client = new InterfaxClient($username, $password, $faxnumber, $texttofax, $filetype);
       $result = $client->SendFax;  
       echo $result;

       ?>
instead of this code:

       <?php
        
       $client = new SoapClient("http://ws.interfax.net/dfs.asmx?wsdl");
        
       $params->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?

17 comments

[ 2.9 ms ] story [ 49.0 ms ] thread
toyg
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.

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

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

faxman
OK, thanks. Going back to the drawing board with renewed vigor!
JS_startup
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.

faxman
> ... conditioned to vote for REST over SOAP.

Yes, I dread to think I'm going through a lengthy project just to address a current fashion trend...

arghnoname
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?
faxman
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.
cheald
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.

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

That was exactly my thought. I was looking for reinforcement of the possibility that people will still want the entire REST interface visible and documented even in the presence of wrapper libraries.

cheald
Personally, I prefer REST interfaces, because it always seems like vendor libraries have just enough suck in them to make me want to use my own.
DougWebb
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.)
jefflinwood
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.

faxman
> only maintain libraries for your SOAP endpoint (at least for now

Check. This was the decision that came out of today's product meeting after reading responses here.

> Put up a form...

Check. Already did this a couple weeks ago at www.interfax.net/en/dev/rest. Already got a few bites.

> Just because someone on a survey said they wanted REST instead of SOAP ...

I agree. However, we ran several variations of the survey including one where developers had an opportunity to say that not having REST is a show-stopper for them, which got us worried.

Strangely, most of those who insisted on REST develop in environments which have the strongest SOAP support, like C#, PHP, and Java. This got me thinking that we might be dealing with fashion issues more than practical issues...

[deleted]
(comment deleted)
[deleted]
(comment deleted)
[deleted]
(comment deleted)