Skip to Main Content

Introduction to REST APIs



Representational State Transfer, or REST, is any interfaced based on the HTTP standard that is used both for obtaining data and for performing operations over them across a wide range of formats, whether JSON, XML or others. Its simplicity is extreme when compared to standard data transfer protocols used until a few years ago, such as XML-RPC, and especially SOAP.

REST APIs makes it easy to create applications and services that can use different clients and devices. The only requirement is that they handle HTTP, which is quite common, for example, for any web developer.

-Keep learning: What are the advantages of REST APIs?-

Roy Fielding, an expert in network architecture and one of the main authors of the HTTP specification, was who defined REST in 2000. It was him who detected the need to accomplish a more natural, standardized architecture to create APIs focused on providing Internet services. In fact, REST is often times considered to be, above all, a framework focused on web application development.

Scalability of REST APIs

Among REST APIs features, we can highlight that it is not necessary to store the server’s state; all information should therefore be available to be queried by the client. This is a significant advantage, since it allows for scalability without the need to worry about storing session variables. In addition, it is possible to use various technologies to provide resources or specific parts of a single API.

-Wait!:What are the differences between REST and SOAP?-


When developing a web application, and in particular, an API, three grades are involved when using REST. Leonard Richard, the great icon of resource-oriented architecture, set them forth in a model he dubbed the ‘Richardson Maturity Model’.

  • Proper use of URIs (Uniform Resource Identifier). URLs (Uniform Resource Locator) are in charge of identifying the resource, in addition to facilitate access to it and allowing us to share its location. By resource we mean information (a page, file, section information) we want to access, modify or delete. URIs should maintain a logical hierarchy, be format-independent, and be unique for each resource. When naming them, it is advisable to avoid verbs. You need to remember that URIs are not suitable to perform information filtering over a resource.
  • Proper use of HTTP. The three keys to developing REST APIs are http methods, status codes and acceptance of content types. HTTP provides the following methods to handle resources: GET (query and read resources), POST (create resources), PUT (edit resources), DELETE (delete resources) and PATCH (edit specific parts of a resource).

The Accept header is suitable to specify, in HTTP, in which format we intend to receive a resource, and even to specify many, in order of preference. The API is capable of returning a resource in the first available format. It will return the HTTP 406 status code in case the resource cannot be displayed in the formats specified by the client with the Accept header. For the client to be aware of the returned format, the Content-Type header will be provided.

Implement Hypermedia. This is useful to connect client applications with APIs via links, which allows them not to worry about knowing beforehand how to access resources. It involves adding extra information to the resource. Hypermedia offers two additional advantages. On the one hand, it automates processes between APIs without the need for human interaction. On the other, the client does not need to know resource URLs. In this manner, if URLs were to change, no maintenance would be required on each of the resources.