Writing the interface to a web service API

Question

I'm beginning to design a web-based API and the very first issue—how will users interact with it—left me at a loss. This is an API that is only going to be used by other folks within our company and will be used by people who have some programming knowledge, so there's a good bit of leeway in all respects, and it needn't be simple enough for laymen.

Should I have a single URL and have all the information passed as query parameters:

http://hostname/api/v1?func=getZipCode&state=Ohio&city=Toledo&street='100 Cherry Street'

Or something RESTful:

http://hostname/api/v1/getZipCode/Ohio/Toledo/100 Cherry Street

Or is SOAP the way to go:

POST /api/v1 HTTP/1.1

<?xml version="1.0"?>
<soap:Envelope>
<soap:Body xmlns:m="http://hostname/api/v1/wsdl">
  <m:getZipCode>        
    <m:state>Ohio</m:state>
    <m:city>Toledo</m:city>
    <m:street>100 Cherry Street</m:street>
  </m:getZipCode>
</soap:Body>
</soap:Envelope>

What are the (dis)advantages of each approach?

Answer 1

Your example of "REST" really has nothing to do with REST at all, it's just a pretty URI. Check other questions on StackOverflow which explain what REST is, or read Fielding's dissertation on REST for the authoritative source.

One advantage over SOAP and RPC that REST has is a less brittle API, due to minimized coupling between URIs and resources. In REST, you navigate resources via hypertext - each resource representation response would include URIs of related resources, so that the only URI you need in your published API is a single entry point. In RPC, you generally include every possible URI in your API, which is a huge amount of coupling and excessively brittle. The server should be able to manage its own URI space, as in REST.

In SOAP, you just use one URI for everything, which you POST to. POST requests are not cached, so that is one huge disadvantage. SOAP doesn't try to fit into the HTTP stack like REST does - it just uses HTTP as a tunnel.

Answer 2

What language(s) do you clients use? What tools do they have to consume your services? I would focus most on choosing something that is well supported in their programming environments.

I've had good success with both REST and SOAP in terms of consumability. My Java-implemented services have been consumed with no great technical effort by .NET developers.

The SOAP approach is part of the whole WesbServices in its WS-* guise: there are variations and extensions to this for fine-grained security, asynch delivery, transactions and all sorts of other good stuff. If those more heavyweight requirements are likely to feature in the future I would go with SOAP.

If your consumers are more likely to be AJAX clients in the browser then REST with JSON payloads may fit really well.

Summary, focus on the clients' needs and capabilities. Make their life easy.