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

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)