The REST Architecture

1. Introduction

REST is a software architectural style that relies on rules that describes how to define and access resources. As we can see on Google Trends, interest in REST is huge. It’s hard to imagine the moderns Internet without RESTful APIs. In this article, we’ll dive deeply into REST and related HTTP concepts.

2. REST Architecture

As we mentioned, the REST is a software architectural style. On the other hand, it isn’t standardized (like SOAP). It gives a lot of elasticity as it comes to implementation. For example, there is no single and appropriate way to implement pagination. Therefore, REST defines a set of main, general constraints to follow while developing RESTful APIs. Let’s define them.

2.1. Constraints

• Uniform interface. Specific resources should be identified in the request. Usually, they are described by Uniform Resource Identifier (URI). Moreover, internal implementation is separate from resource representation. Further, representation should provide all information to modify or delete the resource or fetch additional data.
•  Client-server architecture. The client uses URIs to obtain resources. It doesn’t concern how the server process the request. On the other hand, the server process and returns the resources. It doesn’t impact a user interface in any way. Both client and server don’t need to know about other responsibilities. Thus, they can evolve independently. It allows using a single API in many different clients, e.g., web browsers, mobile apps.
• Statelessness. A RESTful API should be stateless. In simple words, it means that it doesn’t store any information about the user’s session. Therefore, every single request should provide complete data to process it. Thus, it leads to greater availability of the API.
• Cacheability. The server’s response should provide information on whether it should be cached and for what time or not. Caching the data that updates rarely improves performance and eliminates redundant client-server interactions.
• Layered system. A REST API can consist of multiple layers, eg., business logic, presentation, data access. Moreover, layers shouldn’t directly impact others. Further, the client shouldn’t know if it’s connected directly to the end server or intermediary. Therefore, we can easily scale the system or provide additional layers such as gateways, proxies, load balancers.
• Code on demand. This one is an optional constraint. The server can return a part of the code itself instead of the data in JSON format. The point is to provide specific operations on the data that the client can use directly. Although, it’s not a common practice.

3. HTTP Protocol

Considering REST we usually think of HTTP-based applications. Although, it’s possible to use REST for different protocols but it happens very rarely. Thus, in this section, we’ll focus on HTTP protocol and its usage with REST.

To begin with, an HTTP protocol is the protocol of the World Wide Web. It defines the rules of communication between a client and a server. HTTP is stateless and it works in a request-response approach.

A client sends a request related to some resource. It can be an HTML website, a file, or javascript code. HTTP doesn’t define what a resource should be. Each resource has its own identifier calls URI. A general structure of URI looks as follows:

scheme:[//[user[:password]@]host[:port]][/path][?query][#fragment]

To clarify, let’s see a real-world example:

The URI is only a part of the HTTP request. The request consists of:

• the request line with path, protocol version, and HTTP method
• zero or more headers
• an empty line that indicates the end of the headers
• an optional body

3.1. Methods

We already know, that the HTTP request consists of the request line and there is the HTTP method. The HTTP method describes the action that the client wants to perform on the resource. There are four basic, most used methods: GET, POST, PUT, and DELETE. Let’s define them.

The first one, GET is used to read the resource. The server returns the resource for the given URI. The GET method doesn’t contain a body. It only fetches the resource and doesn’t modify it in any way.

The second one, POST is used to transfer data to the server. Thus, it’s usually associated with creating a resource. The data are sent in the body. After the resource is created, the server should respond with its URI.

The next one, PUT is similar to POST. Although, it differs significantly. It’s used to update the existing resource. It overrides the whole resource with transferred data. The main property, that differs PUT from POST, is that PUT is an idempotent operation. That means calling PUT with the same data many times will always give the same result. It doesn’t have any side effects. Moreover, PUT points to an existing resource. Whereas POST creates a new one.

The final basic method is DELETE. As the name suggests, it’s used to delete an existing resource.

There are also additional methods, that could be sometimes used: PATCH, HEAD, OPTIONS, CONNECT, and TRACE. Although, there are rarely used and we won’t cover them in this article.

3.2. Codes

The HTTP response comes with the response code. It informs about the result of the operation. It’s especially useful for UI developers, as they can perform appropriate action basing on the code. There are the following groups of HTTP response codes :

• 1xx – informational – indicates that the request was received and the process is continued. The examples are: 100 – Continue, 101 – Switching Protocols
• 2xx – success – when the request was received, understood, and successfully processed. The well-known examples are 200 – OK and 201 – Created
• 3xx – redirection – client needs to take additional action to fulfill the request, e.g., 300 – Multiple Choice or 301 – Moved Permanently
• 4xx – client errors – indicates that there is an error on the client’s side, such as 400 – Bad Request or 401 – Unauthorized
• 5xx- server errors – informs that an error occurred on the server’s side, e.g., 500 – Internal Server Error, 501 – Unimplemented

4. Richardson Maturity Model

In simple words, the Richardson Maturity Model estimates the level of compliance with the requirements of the RESTful API. The model defines four levels. If the API meets all of them that means it fully implements the model. Thus, it indicates that the API is of good quality considering the REST constraints.

Level 0 is called The Swamp of POX. On that level, API doesn’t use the full potential of the HTTP protocol, usually, it uses POST and GET methods only. Thus, the HTTP protocol is only used as a transport layer. Moreover, mostly response codes 200 are returned. Further, the implementation doesn’t rely on well-defined URIs. Example endpoints of level 0 API could look as follows:

POST /api/createUser
POST /api/updateUser
GET /api/findUser

The level 1 API defines resources and their URIs. Although, still additional HTTP methods and response codes aren’t used. The example URIs of level 1 API are:

POST /api/users/create
GET /api/users/{id}/find
POST /api/users/{id}/update

On level 2 API uses additional HTTP methods besides GET and POST such as PUT, PATCH, or DELETE. Therefore, URIs are better defined. Moreover, API uses more meaningful HTTP response codes. Below, we can see an example level 2 API endpoints:

POST /api/users
PUT /api/users/{id}
GET /api/users/{id}

Finally, level 3 introduces HATEOAS. it’s a self-navigating API. It adds some complexity, thus it’s not often used. In simple words, we add URIs of additional resources related to the demanded resource. To clarify, let’s look at the below example. In a user response, we embedded an address URI and by using it the client can fetch the address details.

{
   "id":12345,
   "firstname":"some-firstname",
   "lastname":"some-lastname",
   "age":39,
   "links":{
      "address":"users/12345/address"
   }
}

5. Conclusion

In this article, we defined REST architecture fundamentals and constraints. Moreover, we described HTTP protocol and its usage in RESTful APIs. We can see, that REST is solid and elastic architecture. Therefore, it’s so popular and widely used in many modern APIs.