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> <?php
require('Interfax.php');
$client = new InterfaxClient($username, $password, $faxnumber, $texttofax, $filetype);
$result = $client->SendFax;
echo $result;
?>
</code></pre>
instead of this code:<p><pre><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;
?>
</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?
I hope you are not trolling.<p>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.<p>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.
If your clients only use your provided libraries then there <i>is</i> 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.<p>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:<p>* 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.<p>* 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.<p>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.<p>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.
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.)
The primary appeal of a REST interface is simplicity. You don't <i>need</i> 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.<p>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.
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?