What is a REST API?

Let's start by recalling what an API is: an "Application Programming Interface" is a set of features available through a simplified abstraction layer allowing software to be developed by "consuming" this layer.

If you want to learn more about APIs, our article API vs SDK is still online!

This definition holds true for REST, GraphQL, SOAP APIs, etc... But what differentiates a REST API from the others?

That's what we're going to see together!

The characteristics of a REST API

Designed for the web

Some APIs are made available by the operating system, by the browser, and others by servers available on the Internet.

The concept of REST is based on the HTTP protocol, so it is inseparable from the Internet, and more precisely from the web.

Of course a REST API can be consumed from any system or language, the only prerequisite is the ability to make HTTP requests

State vs Transactions

To begin with, you should know that "REST" stands for "Representational State Transfer", and this definition is not meaningless.

Some APIs (SOAP and GraphQL for example) offer an abstraction based on transactions, like this:

- listArticle()
- createOrUpdateArticle(data)
- deleteArticle(Id)

Here the term transaction is a synonym for a set of operations, functions executed in a certain order

Whereas REST is based on the direct representation of data. Instead of exposing available transactions, it exposes resources in the form of URLs in order to represent the state of the data.

Example:

• GET /articles (Returns all articles)
• GET /articles/1 (Returns the details of article 1)
• POST /articles (Creates a new article and returns it)
• PUT /articles/1 (Modifies article 1 and returns the modified article)
• DELETE /articles/1 (Deletes article 1)

Here we can see that each call will only affect the resource in question, and that each method for updating a resource is independent.

For example, to recreate the same behavior as the previous transaction createOrUpdateArticle(data), you would need a GET call, then a POST or PUT call.

That's why we talk about data representation, and not transactions, for a REST API.

The rules of a RESTful API

To summarize the concept of a REST API, it's an API that allows resources to be retrieved and modified through HTTP calls and methods.

But to go further and design a standardized RESTful API, there are 6 rules to follow.

If and only if these architectural constraints are respected, then we can speak of a RESTful API. Here are the 6 constraints to respect in order to design an API according to best practices:

1 - Uniform interface

A uniform interface means that every call to the API will have the same form, that every type of call must have the same behavior and that every response will be formulated in the same way.

This standardization mainly concerns how each resource is targeted, how data is transmitted and what operations are applied to them.

Here are the important points to respect:

1.1 - URI = Resource

The most important part of a request is the resource, it is represented by the URI (Unique Resource Identifier) and can contain parameters to specify a precise resource.

Example:

• /houses => The list of all houses
• /houses/1 => The details of house n°1
• /houses/1/rooms => The list of rooms in house 1
• /houses/1/rooms/1 => The details of the first room in house n°1

1.2 - HTTP Method = Action

Next, to act on a resource, we use HTTP methods, as follows:

• GET to list, retrieve one or more resources
• POST to create a resource
• PUT to update a resource
• DELETE to delete a resource

Good design of a RESTful API relies in particular on respecting the semantic rules of HTTP such as idempotence

1.3 - Request body = Data

Data (sometimes called payload) will be passed in the body of the request for HTTP methods that allow it, namely POST and PUT requests.

There is no limitation on the format of data passed to the API, the JSON format is often used, but you can also find APIs accepting XML, BLOB, etc. formats.

Some APIs accept and even accept/return several different types, related to the information contained in the "Accept" and "Content-Type" headers.

1.4 - Headers = Metadata

All the additional information required by the API for it to function properly, such as:

• Authentication data
• The language

...will be communicated through the request headers, such as "Authorization", "Accept-Language", etc...

1.5 - Status code = Result

The result of operations performed by the API should always be represented by the corresponding HTTP status code, always keeping in mind that the API's semantics should be as explicit as possible.

Some examples of the most common return codes:

• 200 => Success
• 201 => Success, a new resource has been created
• 404 => Resource not found
• 400 => Problem with the request

One example to avoid is, for instance, returning a 200 code, with an "Error: xxxx" message in the body of the request.

If you want to learn more about the HTTP status codes you absolutely need to know, here's a dedicated article.

1.6 - HATEOAS

HATEOAS stands for (Hypermedia As The Engine Of Application State), and behind this acronym actually lies a fairly simple concept.

A RESTful API is not only supposed to provide the data of a resource, but also direct (hypertext) links to related resources in order to make navigating resources simpler, and automatable.

For example, a call [GET api.example.com/articles/1] will give you the details of a blog article, including the author's name, but the response will also contain a link to "api.example.com/author/2637" in the author object!

2 - Client-Server

This constraint seems obvious when comparing a RESTful API to GraphQL for example, but as explained at the beginning of the article, there are many APIs made available by the system, and not through a remote server.

A REST API, on the other hand, necessarily operates according to a client-server architecture!

3 - Stateless

The "stateless" constraint describes a mode of operation in which no information is kept on the server between two consecutive calls.

The most telling example remains that of authentication: by using a session system stored on the server, the latter keeps a state in memory, which is referred to as "stateful" operation.

A "stateless" API will instead use token-based authentication (for example), and the user's information will be stored in a database and retrieved with each new call, thanks to the token provided in each request.

This notably allows deploying your API across several machines, in order to scale horizontally, without risking losing the current state of a machine, and therefore a user's authentication.

4 - Caching

Unlike some other types of APIs where caching is not a priority, read (GET) calls of a RESTful API must be cacheable in order to optimize performance when retrieving data.

5 - Layered system

This constraint does not mean that your API MUST contain several layers, but MAY contain several layers.

For example, you can imagine your API server running behind a certain number of other servers, such as a cache server, a (reverse) proxy, a load balancer, etc...

The constraint here is that the requests and responses of your REST API must not be affected by these intermediaries, this must be completely transparent for the client sending and receiving these requests.

6 - Code on demand (optional)

The "Code-on-demand" constraint is the only one that is optional, first because it doesn't meet the needs of every project, and because there can be some security implications.

In theory, a client is able to request code from a RESTful API, which will then be contained in the body of the response, to be executed on the client.

For example, one could imagine a script tag retrieved and containing a specific calculation method for a piece of data, used by the front-end of an application.