

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

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.<p>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.<p>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:<p><pre><code>       &#60;?php

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

       ?&#62;
</code></pre>
instead of this code:<p><pre><code>       &#60;?php
        
       $client = new SoapClient("http://ws.interfax.net/dfs.asmx?wsdl");
        
       $params-&#62;Username  = $username;
       $params-&#62;Password  = $password;
       $params-&#62;FaxNumber = $faxnumber;
       $params-&#62;Data      = $texttofax ;
       $params-&#62;FileType  = $filetype;
        
       $result = $client-&#62;SendCharFax($params);
        
       echo $result-&#62;SendCharFaxResult;  
       ?&#62;
</code></pre>
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?
======
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...

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

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

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

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

