RESTify your API

Last night I was discussing RESTful architecture on Twitter with Emil Stenström. Specifically how yet another API said it was RESTful, when it really was not.

You see these all the time now and while some will claim the term has lost its original meaning, I think REST is way too nice to have diluted because a bunch of jimmies could not be arsed to RTFM.

So I wanted to whip up a blog post to show how to move this API from its current RPC like style, to being truly RESTful. Five hours in I realized it had grown out of control and would take me the entire day to complete… Since I do not have that kind of luxury and because others have already explained it so well, instead I will curate their efforts.

RESTful reading

Discoverability. Jeremy H goes through how to consume a RESTful API in a way that concretizes the discovery aspect of REST. Media types, like application/vnd.example.coolapp.apiIndex-v1+xml are defined by the API and these should be the major focus of the documentation.

Cachability. Mark Nottingham has an excellent caching tutorial, which can help shed some light on the important cachable property of a RESTful API.

Web basics. Because REST tunes in well with the HTTP protocol, RFC 2616 and RFC 3986 are well worth at least skimming through.

RESTful criteria. Yours truly goes through the RESTful criteria.

Workflow and links. InfoQ shows how to order a cup of coffee by means of a RESTful API.

HATEOAS. Matt Cottingham explains clearly what hypermedia controls is and why HATEOAS is important.

Maturity model. Tobias Nyholm commented with a link to an very good read on Richardson Maturity Model, by Martin Fowler.