REST API: the architectural constraints
By: Girija Shankar Behera
Tags: PROGRAMMING REST APIS, Programming Rest Apis

Upon successful updation, the server returns with Status 200 and the updated repo information. If I want to delete it, again I use the URL returned in this step with DELETE method.

5. Delete the repository with its URL and DELETE method. Image by Girija Shankar Behera

The DELETE method returned with no content, hence 204 status code.

II) Manipulation of Resources through Representations:

These operations ensure the second sub-constraint in the constraint Uniform Interface, i.e. Manipulation of Resources through Representations. When I retrieved all the repositories for my account and when I created a new repository, I used the same URL, but with two different methods. GET once, and POST the second time. Similarly, to update the repository and to delete it, I used the same URL, but with two different methods, PATCH and DELETE. This sub-constraint says that to manipulate the resources, we should use the new representations each time with a different method.

III) Hypermedia as the Engine of Application State (HATEOAS):

Notice how I navigated from one URL to another in each step. I did not go to the API documentation to find the URLs for the specific step. Starting from the first step, the root endpoint gave me a list of all the URLs to hit. Each of them are the hyperlinks to the respective resources.

This sub-constraint says that, each time a client requests for a resource, the server should return with every information that is needed to manipulate the resources. Moreover, it should return with all the corresponding APIs as hyperlinks to move from one to another. Now this makes sense. Even for someone noob like me, I did not face any problem moving from one step to another. Each step returned with a hyperlink to move to a new one. And, we know the HTTP methods as well, which allows us to use the hyperlinks to create, update, delete and what not.

IV) Self-Descriptive Messages:

The sub-constraint mandates that the server should return the Response with every possible meta-information to let a client understand and use it properly. The response comes with ‘Content-Type’ headers which tells the client that the resource returned is in json, or xml or plain text. It comes with ‘Allow’ headers which tells the client all the methods that are allowed to operate on the resource. Similarly, a lot of information is available on the header which makes it easy for the client to understand the Response and take appropriate action.

Layered System

This constraint tells that the architecture of the server can be layered, without letting the client know about it.

Layered Server. Image by Girija Shankar Behera

The above scenario explains this constraint. The server with which client is interacting might only have the APIs deployed on it. It might have nothing to do with the storage of the actual data, or manipulating them, or authenticating the requests with the credentials. So the client has no idea that it is just connected to an intermediary on the way to the end server. This is helpful when we want to scale up the system, or balancing load.

Cache

This constraint tells that the response from a server can be cacheable. With caching the response at the client side, the client does not need to request the server again and again to get the response.

Downside is with cache in place, it needs to be updated each time the data is getting updated server side. There should be no difference in the response that can be retrieved directly from the server or the one from the cache.

There are several headers that give information about caching, in both the request and response. Take a look here to get more details of the HTTP headers used for the providing information on caching.

Statelessness

This constraint is focused on sending the state of the client each and every time it requests the server for a resource. A request should contain everything that is needed to fulfill the request, as the server need not store any session information about the client. The request might include the client credentials or session information or any token issued to the client to validate it, also any context information to understand the request, as the server won’t also store anything from the previous client interactions. Server will validate the client request each and every time with the information sent in the request.

The advantage with this is the server will be free of keeping the session information and managing it. It can process each request individually, and also no need of checking the previous interactions to understand the context.

Code on Demand (Optional)

The last constraint in the REST architecture is Code on Demand, and this is totally optional to use. Server might choose to return a part of the code itself on a request from the client, instead of returning a JSON or XML representation. You can think of it as the client downloading the code and executing it. It would provide support to a part of the application with the client itself.