Skip to main content

REST APIs

An Application Programming Interface, or API, is a type of software interface, offering a service to other pieces of software. Developing a public API means making it possible for external systems to integrate the exposed services into their own, with advantages for both sides.

REST stands for REpresentational State Transfer and is an architectural style; when the principles of REST are respected by a Web API then it can be called RESTful API.

Do you prefer a video?

Here you can find an interesting video about REST APIs.

REST consists of six guiding principles, you can find a description below.

This is a theoretical description of REST

The Fatture in Cloud API loosely applies the principles described on this page.

1️⃣  Uniform Interface​

A Uniform Interface helps simplify and decouple the system architecture.

The following constraints make it possible to achieve a uniform REST interface:

  • Identification of resources: practically, it means that URIs must be used to uniquely identify uniform resources (see below for further information). "Uniform resources" means that the resources interfaces must be standardized and decoupled from the server's implementation of the resource itself (for example using JSON for their representation, while the resource is stored in a database).
  • Manipulation of resources through representation: HTTP verbs are used to create, update and delete resources. Also, if a client knows the representation of a resource it possesses all the information needed to manipulate the resource.
  • Self-descriptive messaged: Each resource representation should carry enough information to describe how to process the message (for example, using Media-Type).
  • Hypermedia as the engine of application state (HATEOAS): The client should be aware only of the initial URI for the REST application, and it should be able to discover all the other available resources using the URIs provided by the application itself. For example, a resource should contain links to correlated resources.

2️⃣  Client-server​

The client-server design pattern enforces the principle of separation of concerns: separating the user interface concerns from the data storage concerns. This principle improves the portability of the interface across multiple platforms and the scalability by simplifying the server components.

3️⃣  Stateless​

The communication must be stateless: each request from the client must contain all of the information necessary to understand and complete the request, and the session is stored completely on the client.

4️⃣  Cacheable​

A response should implicitly or explicitly label itself as cacheable or non-cacheable. If a response is cacheable, the client has the right to reuse it later for equivalent requests.

5️⃣  Layered System​

An architecture can be composed of hierarchical layers by constraining component behavior. It means that each component cannot see beyond the immediate layer they are interacting with; also, it makes it possible to interact with a system using its standardized interfaces without knowing its actual implementation (for example it could be a legacy application).

6️⃣  Code-on-demand (optional)​

The client could extend its functionality by downloading code provided by the server in the form of applets or scripts. This makes it possible to reduce the client complexity: some features will not be implemented by the client itself but provided by the server, while the client will just have to execute the code. At the same time, this makes it possible for the server to delegate some of the processing efforts to the client.

💼  Resources​

Any information that we can name can be a resource. For example, a REST resource can be a document or image, a temporal service, a collection of other resources, or a non-virtual object (e.g., a person).

The state of the resource, at any particular time, is known as the resource representation. It consists of:

  • the data.
  • the metadata describing the data.
  • the hypermedia link that can help the client in transition to the next desired state.

📃  Interface representation​

REST doesn't define an Interface Definition Language, but many have been proposed during the years. The Open API Specification (OAS) is the most used, but some others are available like API Blueprint or RAML.

We use OpenAPI!

We described our API using an OpenAPI specification. For more information, check this page.

📚 Additional Resources​