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.
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
- 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
- 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
- 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.
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.
- GET to fetch a list tweets for the authenticated user.
- POST to create a new tweet
- PUT to update tweet 12345
- DELETE to delete tweet 12345