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’.