REST API: Surely you’ve already heard a lot about RESTful APIs since they are very present in the systems we use daily. But first of all, what exactly does REST mean? And then, what is a REST API? In this post, you’ll discover all you need to know.
Index
What is REST? What does REST mean exactly?
REST: The REpresentational State Transfer is a type of web development architecture that fully relies on the HTTP protocol. It was defined in 2000 by Roy Fielding, one of the ‘fathers’ of the HTTP application layer protocol and a milestone in network architectures.
Today, most applications developed for professional services have a REST API for exchanging information between the front and the back. What makes it so powerful is precisely the isolation it provides between the back-end and any client: web, mobile, etc. Thus, any device/client that understands HTTP can use REST APIs very easily. That is why this type of architecture has gained importance compared to other more complex ones such as SOAP, for the exchange and manipulation of data.
Key features of the REST API
Each resource in REST architecture is identified by its URI (Uniform Resource Identifier)
This URI (endpoint) acts as a unique identifier for each resource in the REST system so that it cannot get shared by more than one resource. The basic structure of a URI is as follows:
{protocolo}://{hostname}:{puerto}/{ruta del recurso}?{parámetros de filtrado (opcional)}
The name of the URI must not contain words that imply actions, and using verbs should be avoided. In addition, the URIs follow a logical hierarchy of layers that allows ordering the resources and encompassing the different functionalities among themselves. For instance:
http://tech.tribalyte.eu/category/apps
Or by adding a body to the REST call in any format. The most used are JSON and XML.
{
"order-by-clause" : "category desc",
"pageSize": 10,
"query-params":[
{
"cond-column": "apps",
"cond-operator":"IN",
"cond-values": [“Desarrollo” , “Salud”]
}]
}
REST API | Using HTTP protocol
If you’re willing to develop a REST API, a deep knowledge of the HTTP specifications is necessary, especially about allowed methods, status codes, and acceptance of content types.
The methods get used to manipulating the different resources that make up the API. The main methods supported by HTTP and therefore used by a REST API are:
- POST: create a new resource.
- PUT: modify an existing resource.
- GET: collect information about a resource.
- DELETE: delete a resource.
- PATCH: modify only a specific part of the resource.
These methods, together with the URI, provide us with a uniform interface that allows us to transfer data in the REST system by applying specific operations on a very specific resource. Although most of the operations that make up a REST API could be carried out through GET and POST methods, extra using them for operations that have nothing to do with the purpose for which they were conceived, can cause a misuse of the protocol away from the standard or the construction of wrong URIs nomenclatures by using verbs.
When a specific request gets made, it is important to know if that operation has been carried out satisfactorily or, on the contrary, some error has occurred. For this, HTTP has a large number of error/success codes that cover all the possible responses users may receive when trying to manipulate a resource by using a REST API.
These are the most common:
- 200 OK – Standard response for successful HTTP requests.
- 201 Created – The request has been fulfilled, resulting in the creation of a new resource.
- 202 Accepted – The request has been accepted for processing, but the processing has not been completed.
- 400 Bad Request – The server cannot or will not process the request due to an apparent client error
- 403 Forbidden – The request contained valid data and was understood by the server, but the server is refusing action.
- 404 Not Found –The requested resource could not be found but may be available in the future.
- 500 Internal Server Error – A generic error message, given when an unexpected condition was encountered and no more specific message is suitable.
A complete example of executing a REST request using a URI
The following is a complete example of executing a REST request using a URI with input parameters and a body to filter data. As can be seen, we also obtain the result of the query in JSON format. The request has got carried out with success, so we receive a code “200 OK”.
HTTP also allows specifying which format we want to receive the resource, indicating several in order of preference, and using the Accept header.
GET: http://tech.tribalyte.eu/category/apps?pageSize=10&page=1
Accept: application/pdf, application/json
Our REST API will return the resource in the first available format but, if not possible, it will display the HTTP 406 Not Acceptable code (the server is not able to return the data in any of the formats accepted by the client, indicated by the client in the ‘Accept’ header of the request).
Generally speaking, the header Content-Type will be displayed so that the user knows which format is returned, for example:
STATUS CODE 200. Content-Type: application/pdf
REST API | Client/server protocol
Each HTTP request contains all the information necessary to execute it, which allows neither client nor server to need to remember any previous state to satisfy it. Nevertheless, some HTTP applications incorporate caching. The client-cache-stateless-server protocol gets configured. That is the possibility of defining some responses to specific HTTP requests as cacheable so that the client can execute the same response for identical requests in the future.
REST API and Hypermedia – HATEOAS
Using hypermedia allows the user client of a REST API to easily access the navigation between resources, as well as connect some resources with others that have some kind of relationship with each other. This exchange of links through the use of hypermedia has its foundations on the principle of HATEOAS (Hypermedia As The Engine Of Application State). This constraint permits that each time a request gets made to the server, part of the response must contain information on links related to the resource consulted. That allows navigation between resources.
{
"empresa": "Tribalyte",
"area": "Technologies",
"categories":
[
"category": "http://tech.tribalyte.eu/category/apps",
"category": "http://tech.tribalyte.eu/category/desarrollo-de-software",
"category": "http://tech.tribalyte.eu/category/salud",
]
}
The main benefits of using a REST API
The main advantage of using a REST API is the independence it provides, regardless of the languages or platforms used.
This allows the same REST API to be used by countless clients and that the change to any other type of user does not cause any impact on it. This feature provides reliability, scalability, and easy portability to any other platform, as it completely isolates the client from the server. The information exchange of the responses needs to be done in a supported format, usually JSON or XML. This separation between the client and the server makes it possible to migrate to other servers or databases in a transparent way, as long as the data is still sent correctly. This makes a REST API one of the most used web architectures due to the flexibility they bring to any work environment regardless of its nature.
How to create a REST API with an expert
Now that you know a little more about RESTful APIs, do you still have doubts or questions about them?
At Tribalyte Technologies we are expert developers of custom apps, software, and, of course, REST APIs. Check our case studies and get in touch with us. We can help you.
CHECK OUR CASE STUDIES
