Practising REST Part 2

Practising Rest Part 1, discusses why “/getUserByEmail?email=” or “/makeUserAdmin?email=” are not RESTful and, therefore, do not yield the benefits of REST. It further discusses what a RESTful API looks like for a users domain and shows the benefits it brings: easy discoverability of your application’s functionalities, ‘API affordance’ (ease of use), simplification of architecture and an improvement in the visibility of interactions which, for instance, makes it easy to think about the security of the system.

Another important aspect of practising REST is using HTTP verbs properly (We are discussing REST in the context of HTTP). As discussed in Practising REST Part 1, the only methods that instruct your application are the HTTP methods: GET, POST, PUT etc. You should use the right verb for the right job. For instance, GET should be used for ‘getting’; POST or PUT for state-changing requests such as updating a Resource.

Two of the ‘constraints’ that the REST Architectural Style derives from are Caching and a Layered Architecture. Caching means that some previous responses from your Server can be stored in a layer between the Client and the Server (the Client inclusive). Those responses can be used, for instance, if the resource being requested has not changed or if a certain time has not elapsed since the previous request. A Layered Architecture means that components can be placed between the Client and the Server to aid request processing. E.g. Using a load balancer.

Using proper HTTP verbs impacts how well your application can benefit from Caching and from a Layered Architecture. For instance, caching rules may be influenced by the HTTP verb used – Cache GETs as they don’t change Application State. The more the semantics of accessing your application differ from what is expected, the harder it is to work with other components. You may have to tweak components more than it’s necessary.

It is better to work with and not against the HTTP protocol on which you are building your application. In that same spirit, it is also important that you use HTTP status codes well. For instance, when a Resource cannot be found, you should throw a 404 rather than a 200 with a message that essentially says that the Resource cannot be found. Using these standard codes makes it easier to work with your API. This is even more so if the developer who is integrating has experience working with RESTful APIs.

Also, when you don’t work with HTTP status codes, you eventually end up creating your own “Response system” which eventually looks very much like ‘HTTP response system’ only that the semantics are peculiar to your application.

Note that using HTTP status codes does not mean that you cannot return descriptive messages. You can return a 404 with a response body that gives the Client any useful descriptions and information that you want.

Thus far, we know not to allow the calling of methods within our application when using REST. Instead, we expose the resources of our application and allow retrieval and manipulation through HTTP methods. We also know to use HTTP verbs properly and to take advantage of HTTP status codes.

One other requirement that is important to practising REST is statelessness. This means that any information that is necessary to processing a request is contained in the request. This is essential for, among other things, benefiting from the layered architecture of the web. For instance, if you were to decide to use a load balancer to load-balance requests, it would be much much easier if state is stored client side rather than server side. Statelessness also increases visibility. Here again, HTTP is a stateless protocol and you should strive to work with and not against the protocol.

What makes HTTP significantly different from RPC is that requests are directed to resources using a generic interface with standard semantics that can be interpreted by intermediaries almost as well as by the machines that originate services. The result is an application that allows for layers of transformation and indirection that are independent of the information origin which is very useful for an Internet-scale, multi-organisation, anarchically scalable information system. – Roy Fielding


Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s