Category Archives: Design

Bad web services API

Posted on by

I’m reading RESTful Web Services Cookbook and on page 17 the author gives this example:

# Request
POST /user/smith HTTP/1.1
Host: www.example.org
Content-Type: application/xml;charset=UTF-8
Slug: Home Address

<address><street>1, Main Street</street><city>Some City</city></address>

# Response
HTTP/1.1 201 Created
Location: http://www.example.org/user/smith/address/home_address
...

There are two problems with this: the first is that “POST /user/smith” has the semantics “register address”, so it would be better if that was clear; the second is that some of the input to the business process is in the XML payload, while some of it is in the HTTP headers (viz Slug). It would be better if all the input was in the payload.

So how would I design this service?

# Request
POST /api/v1/processor HTTP/1.1
Host: www.example.org
Content-Type: application/x-www-form-urlencoded

action=register_address&user=smith&street=Main+Street&city=Some+City&type=home_address

# Response
HTTP/1.1 303 See Other
Location: http://www.example.org/user/smith#home_address

Actually in my designs the /api/v1/processor could be anything, including /user/smith, because the business process is indicated in the request ‘action’ with is submitted with POST. Just like God intended. Idempotency, optimistic concurrency control, authentication, authorisation, auditing, version control, all that good stuff implemented with business logic via business process for ‘register_address’.