Rest APIs (REpresentational State Transfer) are a set of definitions and protocols for building and integrating application softwares. They are platform independant, scalable and support secure communication.
Architectural constraints
Rest APIs were originally introduced in Roy Fielding dissertation written in 2000. The paper defines a client-server data application exchange method over HTTP respecting the following constraints:
- The client is not necessarily aware of the server application advance. This is tointroduce a clear separation of concerns for both (server-client) allowing their code update and improvement in independant tracks.
- The exchange must be stateless, allowing clients to manage their own application state and communicate with the server via requests containing all required information.
- Response made by the server to different client request can be marked cacheable. This allows storing copies of frequently accessed data, which can contribute to the network optimization by reducing bandwith consumption, latency…
- Rest APIs are distinguished among different network-based systems via their uniform-interface feature. This latter allows providing data as resources whith a consistent namespace. More precisely, a system resource should be accessible via a single logical uri (uniform resource identifier) and its access should follow a specific naming convention, link or data format (JSON or XML).
- The purpose of Rest APIs is to separate the client side from the server side. This means that each component is limited to its layer and can be improved or completely modified separately i.e. servers can be scaled via load balancers or shared caches without impacting the clients.
The anatomy of a Rest APIs request
Each APIs request is made up of 4 components
Endpoint : it represents the url defining the requested resource
Method : it defines the request type sent to the server. Several methods are defined to request a resource from the server. The most known are those defining the crud operations:
- Post method: this method is used to create a new database entry since it is sent with a well defined body. Its return must be either a successful entry creation or an error.
- Put method: it is slightly different than the Post method since it is used to update an existing entry in the database. For this reason, its body must represent a new version of an existing db entry identified via its id_key
- Get method: this method is used to get a resource from the server. In other word, a get request performs a read operation of the database
- Delete method: as its name claims, this method is used to perform a delete operation of a resource defined behind the requested url.
Other methods can be used to perform operations on distant resources such as Patch, Head, Options…
Header : Communication between the client and the server is made via the headers concept. It is based on a property-value pairs defining a set of attributes used for different purpose such as authentication, data type definition. The following link defines a set of valid headers.
Body : represents the data sent to the distant resource. It must be filled when sending a Post or Put request and optionally in the case of Delete request (only the id can be used to identify the data to be deleted)
Http status and error messages
The result of an API request is either a correct response or an error. In both cases, the request returns a result status. Each one has a specific code. These codes are defined withvalues ranging from 200+ to 500+. In general, they follow certain rules:
- 200+ : the request is executed correctly
- 300+ : the request has been redirected to another url
- 400+ : a client side error has occured
- 500+ : a server error has occured
Wrapping up
This article is a brief introduction to Rest APIs. It clarifies some theoretical aspects related to their origins, architectural constraints, requests as well as their different responses. In future articles we will be interested in their implementation. Till then, wish you a happy reading ! <):)~
