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"&gt;
  <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

SOAP:

Pros:

• In most languages, its fairly easy to take a WSDL and turn it into raw code. This also gives you basic data objects which is also a benefit.
• Its also relatively easy to generate WSDLs from java and a few other languages

Cons:

• Its a pain in the ass to work with sometimes.
• It can be very verbose. You can end up transferring more markup than actual content.

Get URL:

Pros:

• Can be pretty easy to write the server and server in most languages.

Cons:

• How will you return data back to the user? Will they have to parse some data format?

RESTful

Pros:

• It's "sexy" these days
• Some libraries make it easy to output data in multiple formats

Cons:

• Can be a pain to write depending on the language.
• Unless you really are going to make it "pure REST", its probably not worth the effort (and even then its questionable)

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.

Answer 3

Before looking into specifics of the alternatives above I'd evaluate existing standards in the enterprise. Of course, if there are none then you are indeed free to choose based on your needs and preferences.

But it's unlikely that you build the system API in vacuum. Thus, likely most decisions were already made to embrace one or more approaches and you just need to review those decisions, understand how and why they made them, analyze their relationships and dependencies with the system you build. After this, your choice should become much less uncertain since you are no longer designing just API - you are now designing solution that is part of the system.

UPDATE: ask your future and potential clients what they already use. They don't want to embrace yet another standards and if existing one fits your needs then go with it.

Answer 4

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 5

If you want to be RESTful, don't put some service version like "v1" into an URI. Some ideas about versioning REST Web Services where described by Peter Williams here and here.