Let’s understand what an API isMikelBlockedUnblockFollowFollowingApr 21Photo by Nina Ž.
on UnsplashWhat is REST?REST, REpresentational State Transfer, is a type of web development architecture that is fully supported by the HTTP standard.
REST allows us to create services and applications that can be used by any device or client that understands HTTP, so it is incredibly simpler and more conventional than other alternatives that have been used in the last ten years as SOAP and XML-RPC.
REST was defined in 2000 by Roy Fielding, co-author also of the HTTP specification.
We could consider REST as a framework to build web applications respecting HTTP.
Therefore REST is the most natural and standard type of architecture to create APIs for Internet-oriented services.
There are three levels of quality when REST is applied in the development of a web application and, more specifically, an API that is collected in a model called Richardson’s Maturity Model in honor of the type that established it, Leonard Richardson, father of architecture oriented to resources.
These levels are:Correct use of URIs.
The correct use of HTTP.
Implement Hypermedia.
In addition to these three rules, you should never save state on the server, all the information that is required to show the information that is requested must be in the query by the client.
By not saving state, REST gives us a lot of play, since we can scale better without having to worry about issues such as storage of session variables and even, we can play with different technologies to serve certain parts or resources of the same API.
Level 1: Correct use of URIsWhen we develop a web or a web application, the URLs allow us to access each of the pages, sections or documents of the website.
Each page, information in a section, file, when we talk about REST, we name them as resources.
The resource is, therefore, the information that we want to access, modify or eliminate, *regardless of its format*.
The URL, Uniform Resource Locator, is a type of URI, Uniform Resource Identifier, which, in addition to allowing to identify the resource in a unique way, allows us to locate it to access or share its location.
A URL is structured as follows:{protocol}://{domain or hostname}[:port (optional)]/{resource route}?{filtering query}There are several basic rules to name the URI of a resource:URI names should not imply an action, therefore, you should avoid using verbs in them.
They must be unique, we must not have more than one URI to identify the same resource.
They must be independent of format.
They must maintain a logical hierarchy.
Filtering the information of a resource is not done in the URI.
URIs should not involve actions and should be unique.
For example, the URI /invoices/234/edit would be incorrect since we have the verb edit in it.
For the invoice resource with the identifier 234, the following URI would be the correct one, regardless of whether we are going to edit it, delete it, consult it or read only one of its concepts: /invoices/234.
URIs must be independent of formatFor example, the URI /invoices/234.
pdf would not be a correct URI, since we are indicating the pdf extension in it.
For the invoice resource with the identifier 234, the following URI would be the correct one, regardless of whether we are going to consult it in pdf format, epub, txt, xml or json: /invoices/234.
URIs must maintain a logical hierarchyFor example, the URI /invoices/234/client/007 would not be a correct URI, since it does not follow a logical hierarchy.
For the invoice resource with the identifier 234 of the client 007, the following URI would be the correct one: /clients/007/invoices/234.
Filtering and other operationsTo filter, sort, search or search information in a resource, we must make a query about the URI, using HTTP parameters instead of including them in it.
For example, the URI /invoices/order/desc/date-from/2007/page/2 would be incorrect, since the invoice listing resource would be the same, but we would use a different URI to filter, classify or locate it.
The correct URI in this case would be:/invoices?date-from=2007&order=DESC&page=2Level 2: HTTPKnowing well HTTP is not optional for a web developer who cares about their work.
Although the RFC is easy to read, if you are interested in learning the basics of this protocol well, the orientation of O’Reilly is strongly recommended.
To develop the REST APIs, the key aspects that must be mastered and clarified are:HTTP methods.
Status codes.
Acceptance of content types.
MethodsAs we have seen in the previous level, when creating URI we should not put verbs that imply action, even if we want to manipulate the resource.
To manipulate resources, HTTP gives us the following methods with which we must operate:GET: To consult and read resources.
POST: To create resources.
PUT: To edit resources.
DELETE: To eliminate resources.
PATCH: To edit specific parts of a resource.
For example, for an invoice resource:GET /invoices → Allows us to access the list of invoices.
POST /invoices → Allows us to create a new invoice.
GET /invoice/123 → Allows us to access the detail of an invoice.
PUT /invoices/123 → Allows us to edit the invoice, replacing the entire previous information with the new one.
DELETE /invoices/123 → Allows us to delete the invoice.
PATCH /invoices/123 → It allows us to modify certain information of the invoice, such as the number or date of the invoice.
Perhaps due to ignorance or the support of certain browsers, web developers have used, during the last few years, only the GET and POST methods to perform all these actions.
If we work with REST, this would be a basic error and can give us problems even when it comes to assigning a name to our resources, which forces us to put verbs in the URLs.
Status codesOne of the most frequent errors when creating an API is to reinvent the wheel when creating our own tools instead of using those that have already been created, thought and tested.
The most reinvented wheel in the development of the APIs are the error codes and the status codes.
When we perform an operation, it is vital to know if this operation has been carried out successfully or, in the opposite case, why it has failed.
A common mistake would be for example:Request=======PUT /invoices/123Response========Status Code 200Content:{ success: false, code: 734, error: "Insufficient data"}In this example, a status code of 200 is returned, which means that the request was successful, however, we are returning an error in the body of the response and not in the requested resource in the URL.
This is a common error that has several drawbacks:It is not REST nor is it standard.
The client that accesses this API must know the special operation and how to deal with its errors, so it requires an important additional effort to work with us.
We have to worry about keeping our own codes or error messages, with all that implies.
HTTP has a very wide range that covers all the possible indications that we are going to have to add in our answers when the operations have gone well or badly.
It is imperative to know them and know when to use them, regardless of what you develop following REST.
The previous example would be correct in the following way:Request=======PUT /invoices/123Response========Status Code 400Content:{ message: "A customer id must be specified for the invoice"}Types and formats of contentWhen we talked about URL, we also saw that it was not correct to indicate the type of format of a resource that we want to access or manipulate.
HTTP allows us to specify in what format we want to receive the resource, being able to indicate several in order of preference, for this we use the Accept header.
Our API will return the resource in the first available format and, if the resource can not be displayed in any of the formats indicated by the client using the Accept header, it will return the HTTP status code 406.
In the answer, the Content-Type header will be returned, so that the client knows what format is returned, for example:Request=======GET /invoices/123Accept: application/epub+zip, application/pdf, application/jsonResponse========Status Code 200Content-Type: application/pdfIn this case, the client requests the invoice in compressed epub with ZIP and if not, in pdf or json in order of preference.
The server finally returns the invoice in pdf.
Level 3: HypermediaDespite what may lead us to think about the term retrofuturist hypermedia, the concept and purpose it tries to describe is quite simple: *connect through the links of client applications with APIs*, allowing these customers worry about knowing in advance how to access resources.
With Hypermedia we basically add extra information to the resource about its connection to other resources related to it.
Here an example:<order> <id>666</id> <status>Processed</status> <links> <link rel="invoice"> http://example.
com/api/order/666/invoice </link> </links></order>In this example we see how to indicate in an xml that represents an order, the link to the resource of the invoice related to it.
However, we need the client that accesses our API to understand that this information is not specific to the resource, but is added information that can be used to link the order with the invoice.
To do this, we must use the Accept and Content Type headers, so that both the client and the API know they are talking about hypermedia.
For example:Request=======GET /order/666Accept: application/our_api+xml, text/xmlResponse========Status Code: 200Content-Type: application/our_api+xmlContent:<order> <id>666</id> <status>Processed</status> <links> <link rel="invoice"> http://example.
com/api/order/666/invoice </link> </links></order>As we can see, the client requests the application/our_api+xml format preferably in text/xml format.
In this way, it tells the web service, that it understands its hypermedia format and can take advantage of it.
The web service therefore, as it implements hypermedia, returns the resource information and hypermedia information that the client can use.
Hypermedia is useful for example so that the client does not have to know the URLs of the resources, avoiding having to do maintenance on each of them if in the future said URLs change (which should not happen).
It is also useful for automating processes between APIs without human interaction.
ConclusiónAs we have seen, the basic principles for building REST APIs are based on knowing mostly HTTP, something that is not optional for a web developer.
.