How to REST?

Today I tried to explain REST (as in REpresentational State Transfer, not near sleep) to a manager and why some of the services deployed at the organization he was working for wasn’t REST. While there isn’t a formalized spec, there is a dissertation by the Roy Fielding, who came up with the REST-principles as a set of principles that guided him while shaping the HTTP 1.1 standard which only recently got a successor with version 2.0… REST is a set of principles/guidelines that are very stable & predictable. It is also very simple, and theirin lies both its strength, and the sometimes too loose application of its principles.

Apparently many developers didn’t get ‘the web’ (HTTP) right, hence REST was developed as a basic set of principles to explain how HTTP is supposed to work. This is a list of my favourite parts, also based on some secondary resources.

Some key concepts.

REST is about the resources

While RE in rest stands for Representation, it is the representation of a resource. Through representations ultimately resources are being manipulated at the server’s side. Manipulation is done by returning the modified representation to the server. To manipulate a resource, you send a message to that resource.

URL or URI or URN

URN’s and URL’s are both URI’s. Universal Resource Identifiers. Universal Resource Names tell less about how to locate a resouource when compared to URLs, hence, to keep things simple, I like to use URL’s, and just try to use a single URL for a single resource (one to one mapping). Theoretically this can be more complex, but if you’re controlling the entire design of the API and the world it operates on, please keep it simple.

Don’t create fake resources

Something that I care deeply about, but may not be as explicit in the spec: While different versions of a document can be considered unique resources, hence with unique URLs, it is common place to see ‘actions’ as resources. E.g. ‘…/order/1/pay’. However, there is no resource that can be described as the ‘to be paid resource’, that is different from the resoure that is not paid yet. It is the same. If the paid state is part of the order resource one could simply update the resource, and PUT a new version in place. More likely, another resource is responsible for paid-status, namely a payment. It would hence make more sense to have a POST to /payments with a reference to the resource the payment is for. Or a post to /order/1/payments. There is no verb in resource.

GET PUT POST DELETE…

Stick to the basic HTTP operations for manipulating resources. You cannot put verbs in the resource, as there is no verb in the resource, but there are also just a limited number of ‘verbs’ to work with. And that works totally fine. Simply use the basic HTTP methods such as GET to get (a cacheable) representation of a resource, PUT replace/change a resource; POST to create and DELETE, well to delete a resource.

Discoverability

To me there are two parts to discoverability. First of all there is the predictability of the resource structure that comes from the REST-design. But when talking about discoverability actually means that a properly implemented REST interface should also give pointers to how to perform related operations; links to for example the overview of all resources of that type, or related resources, or as Fielding put it in his original dissertation: “The model application is therefore an engine that moves from one state to the next by examining and choosing from among the alternative state transitions in the current set of representations. Not surprisingly, this exactly matches the user interface of a hypermedia browser.” (Section 5.3.3, last paragraph)

This idea is now commonly referred to as HATEOAS; Hypermedia As The Engine Of Application State. Here, the API response would suggest the methods that an User Interface could provide to the end-user.

Good luck implementing your next REST api. And don’t dismiss it yet in favor of yet another cool new technique.