We already talked about the WEB Apis, now we are going to talk about a style of how to make web apis: Rest.

Rest, which stands for Representational State Transfer, is a style of building web services which adhere to a set of established principles or conditions. So, the idea here is that there is a set of conditions that a web API must have to be able to say that it implements Rest. When a web api respects these conditions, we say this web api is restful.

Normally, when we consume a web api, it is because we want to access its resources. In our context, a resource refers to things or entities that you can consume from a web api. For example, if we have a web api that allows us to work with the system of a library, a resource that the web api could expose would be the list of books in the library. Another resource that the web api could expose would be the list of employees of the library.

An idea that relates to rest is to use HTTP “verbs” on a URL to run different functions of the Web API, for example, suppose we have the URL: https://miWebApi.com/api/User, and we do an HTTP Get on this URL, then we obtain a list of the users, and if we make an HTTP Post to this same URL, where we send the information of a user, then we will execute the functionality of creating a new user on our server. We call this HTTP CRUD, because we can create, read, update and delete information by consuming a web API using HTTP, however, this is not enough to say that a web API is restful. In the following blogpost we will talk about HTTP verbs, for now, let’s concentrate in the conditions that make a web api be restful.

The advantage of respecting these conditions is that, in general, we have added benefits, such as software that can be developed and respond to changes in business requirements in an efficient manner. It is important to point out that not all the Web API’s that you build have to be restful, in the end, rest is just a guide to develop web apis, which you do not have to follow to the letter so that your web api is “good”.

As we said, for a Web API to be restful, it must respect the 6 conditions of Rest. Let’s now talk about these six conditions:

1) Client-Server Architecture

The server client architecture tells us about the separation between a client and a provider or server. In the case of web apis, the server is a web server; The client can be any software capable of communicating using HTTP with the web server. For example, a web page in a browser, an application in a cell phone, and even a desktop application. With this principle, we assure the separation of responsibilities between our api web service and the clients that consume said service. Thus, our web api can evolve on the server, and that does not necessarily have to affect the customers of our service.

2) Uniform Interface

The idea of ​​the uniform interface is to have a standardized way of transmitting information. With this condition, we have a “universal” way to use common web apis. The idea then is that, if you know how to consume a web api, you know how to consume other web apis without much difficulty. The uniform interface condition asks us for 4 sub-conditions:

– Resource identification: We use URL’s to identify resources. Thus, we can use the URL: https://miApi.com/api/books to access the list of books on our web api, assuming that our web api exposes this resource.

– Manipulation of resources using representations: The idea here is that if the client has a way to access the resource, typically a URL, then with this he can modify the resource. In our case, we will use HTTP verbs for this. More information about this in the next entry.

– Self-descriptive messages: All messages are complete, in the sense that they indicate all the information necessary for them to be worked on by the server in a satisfactory manner. When we talk about messages, in our case we refer to HTTP requests that we make to the server. Something that a message can indicate is the format in which you want the information of the server, for that we can use media types.

Media types are format identifiers that we use to indicate how we want the information to be given to us. For example, we can request that the information of the web api be given to us in json format, XML format, pdf format, etc. Of course, it is important to emphasize that, although the client has the power to request the information in the format you want, it is the server’s responsibility to satisfy the client’s request. If the client’s request is not reasonable, the server does not have to satisfy it. For example, if the client wants a list of books from the web api, and asks for it in jpeg format, which is an image format, this does not even make sense, so our web api does not have to satisfy that demand. However, it is reasonable that the client can request this information in XML or JSON format.

– Hypermedia as the engine of application state (HATEOAS): This means that the information that gives us the web api when we make a request must include links to be able to continue exploring the other resources of the web api. For example, if we ask for a list of books from our website api, it would be ideal if each of those books has a link which allows us to see the detail of each of the books.

3) Stateless Protocol

Each of the requests made to the website api have all the information necessary for the request to be resolved satisfactorily. Thus, if our web service requires the client to be properly identified to access and manipulate a resource, then the client must send us some type of information that identifies the client that is making the request each time an HTTP request is made to the server.

4) Cache

The responses of the web api should indicate when they should be cached. When we talk about cache, we mean that the client can save the resource given by a url locally, so that in subsequent http requests, this resource does not have to be requested from the web api, but the version can be consumed local. This decreases the response time that customers of our application should expect. Not everything should be saved in cache, as this puts our clients at risk of working with outdated data.

5) Layered System

The server service must have a layer architecture, where its evolution is completely transparent to the client. So for example if your web service will use load balancers, your clients do not have to keep this detail in mind, this must be completely transparent for them.

6) Code on demand (optional)

The web service has the option of sending source code which will be executed on the client. Typically this code is Javascript.

Summary

A rest API is an entire web API that follows the 6 conditions described in this blog post. Not every web API that you do must respect these conditions, it is not obligatory to do it. These conditions are a guide for writing web API’s.