What is REST?

Since I started getting more into back-end engineering, the term REST has appeared many times, often in the context of API design. Everyone wants a REST API, or a RESTful API, but what is that anyways? This humble post tries to explain it in simple terms.

As I do with many things in the tech world, I like to start explaining it by saying what the acronym stands for. In this case, according to Wikipedia, Representational State Transfer is a software architectural style designed specifically for the World Wide Web, our beloved internet. It aims to define how a web application should behave: as a state machine, where a user requests that state in the form of web links, or URLs, and gets the representation of that state in the form of data.

History

Besides unraveling acronyms, another useful way to explain tech concepts is to find out why they were created in the first place. Most technologies were created to solve a specific problem and the REST style is no exception.

In the early 90’s, when the internet was this very new thing everyone was talking about, there was already pressure for the creation of standardized interface protocols that members of the network could use to interact with each other. Organizations such as the W3C and IETF working group, came together to try and organize it. A guy named Roy Fielding worked on such groups and, over the following years, he worked on the REST architectural style and defined them in his PhD dissertation titled “Architectural Styles and the Design of Network-based Software Architectures”. Read more about the history on Wikipedia.

Properties

First, it is important to say what REST is not. It is not a new programming language or framework. It is not software that runs on a computer and it is not a communication protocol, like HTTP. It is a style, meaning that it is a way to organize a software system that makes sense in the context of web applications. In order for an API or system to be considered RESTful, meaning that it applies the REST style, it has to follow some properties by definition.

Client-server architecture. Establishes a separation of concerns between user interface and data storage. This allows for flexibility on both sides, where UIs can be designed independently from the server in many different platforms (Web, mobile, IoT) and the server side can scale horizontally and vertically.

Statelessness. This means that no session information is retained by the server, and every piece of information that is sent across the network exists in isolation from each other or from the context of the session. Every resource is unique and independent. This is important for data-intensive applications where retaining session data could be expensive.

Cacheability. The ability to cache responses allows clients to make better requests to servers and avoid outdated data, for example. This can improve performance.

Layered System. A REST call happens between client and server, regardless of what is in the middle. Load balancers and proxy servers can improve scalability, performance and security of a system without jeopardizing the actual data transaction.

Code on demand. This is an optional property and allows servers to modify or extend functionalities on the client side by sending over compiled code.

Uniform interface. This is probably the most fundamental constraint to define a RESTful service. The communication interface between client and server must be consistent and well defined, so it can simplify and decouple the architecture.

Usage

More than enabling agents in a given network to communicate with each other, the REST standard intends to do so on a large scale, so the true power of the internet can be unleashed. The idea is that the resources on a server where clients will be making requests should be as lightweight as possible.

A resource is a piece of information in the server that will be handed to the client, abstracting all the internal work this server might be doing. For instance, if a client requests a list of names from his Facebook friends, they don’t care if the information is coming from Facebook’s database, from their filesystem or from another service on the web, they just want the information. The REST service works as a layer of abstraction for the client to get the information they need, and that is what makes it simple.

Coming back to the uniform interface property, that interface consists of an endpoint (URL) , a return type and an HTTP method or verb. The endpoint is the location of the resource, where the resource can be anything you are looking for, like JSON data, an image or a file. The return type specifies the type of data being sent over, normally it is JSON, HTML or XML. And finally the verb or method, which is an important part of the request.

The verb or method that comes with a REST call via HTTP defines the type of action we are going to perform with the resource. The verbs are pretty self-explanatory and they are very helpful when building requests:

GET: used to read resources;

POST: used to add new resources;

PUT: used to edit existing resources;

DELETE: used to delete resources;

Finally, the anatomy of a REST call would be something like GET https://mysite.com/api/resource and that would get the data from the specific resource. POST and PUT calls normally have a body of data sent along with the request, that contains the information to be added or edited to the state of the server.

After you call a RESTful service, you should receive a response containing the resource itself and also a status code, that is a standard code that defines the status of the request. The categories for status codes are defined as follows:

1xx: Information;

2xx: Success;

3xx: Redirecting;

4xx: Client Error;

5xx: Server Error;

You probably came across some of those codes when surfing the web, probably the famous 404 Not found code that many websites sometimes return with a funny and creative page. Check out this website for a creative explanation of the status codes.

I hope this article was helpful for clarifying the REST idea and its usage on the web. It is incredibly important for web applications to follow these standards in order for us to have more shareability of resources and information across the internet.