Seventh Octave

Consuming a RESTful Web Service is non trivial at best. Building our Twitter CRM - Tweetlr - showed me first hand how verbosity and inconsistencies manifest in web service design.

Building a RESTful Web Service for others to consume is a whole other story. It's not easy. While I don't believe we need to be saved from REST, I do believe clarity on the principles of REST is both prudent and necessary. Especially, when it comes to best practices in the forth coming ASP.NET Web API.

David Zuelke does an excellent job dissecting what REST is in his presentation Designing HTTP Interfaces and RESTful Web Services:

Working through some examples

At its core, REST is a combination of HTTP Verbs (GET, POST, PUT, DELETE), Resources (e.g. http://twitter.com/tweets/) and the Internet Media Type returned (e.g. JSON, XML, SOAP).

Let's work through some modified examples from David's presentation. Please see the presentation for original examples:

Example #1: Statuses/Show

GET http://api.twitter.com/1/statuses/show/id.format

Problems:

• Operation ("Show") included in the URL
• Status ID not a child of the "statuses" collection

Better: GET http://twitter.com/tweets/id.format

• Show via combo of GET HTTP Verb and tweets Resource

• Internet Media type returned could be JSON, XML, SOAP, etc.

Example #2: Statuses/Update

POST http://api.twitter.com/1/statuses/update.format

Problems:

• Operation ("update") included in the URL
• Uses the authenticated user implicitly

Better: PUT http://twitter.com/tweets/id.format

• User authentication via OAuth or Basic Authentication

• Update via combo of PUT HTTP Verb and tweets Resource

• Internet Media type returned could be JSON, XML, SOAP, etc.

Example #3: Statuses/Destroy

POST http://api.twitter.com/1/statuses/destroy/id.format

Problems:

• Operation ("destroy") included in URL like it's 1997.
• Odd, illogical hierarchy again
• Allows both "POST" and "DELETE" as verbs

Better: DELETE http://twitter.com/tweets/id.format

• Delete via combo of DELETE HTTP Verb and tweets Resource

• Internet Media type returned could be JSON, XML, SOAP, etc.

Summary

At University, during heated debates, a good friend always reminded me not to throw the baby out with the bath water. I think that advice is prudent here.

REST is no more a framework than Agile is. Both are fundamental principles we should use to guide our actions, not restrain them. Fundamentalism is no substitute for passion, reason and debate.

Let's recap:

GET http://twitter.com/tweets/

• GET to fetch a list tweets for the authenticated user.

POST http://twitter.com/tweets/

• POST to create a new tweet

PUT http://twitter.com/tweets/12345

• PUT to update tweet 12345

DELETE http://twitter.com/tweets/12345

• DELETE to delete tweet 12345