REST

No, all of the conversation within your tech team about REST does not relate to relaxation and lazy afternoons (sorry, but you must take the bad dad joke opportunity when given the chance). REST refers to “representational state transfer.” It is an API pattern that has become widely adopted in the last decade.

Increasing internet speed and more powerful computing resources allow applications and services to be fully delivered online. The cloud revolution has caused developers to focus on building more web applications that integrate with other web services easily. For these apps and services to work together, a robust and consistent communication system needed to exist. REST happened because APIs were the wild west and we needed a more “standard” way to plan, configure, build, and manage our APIs.

It made sense to base these standards on CRUD (Create, Read, Update, Delete) principles because that covered the perfect minimal number of functions for just about any editable object you could imagine. Thus POST, GET, UPDATE, DELETE HTTP methods were paired to Create, Read, Update, Delete data actions.

As for the URL patterns of REST, you can follow those patterns along with a simple URL pattern like this:

Or in a more tangible example of REST:

A Quick Look at Client-Server Architecture

Before we further explore what REST is, let’s take a look at the underlying client-server architecture.

The client-server model is an application structure where workloads are divided among clients and servers. Clients request resources to servers that host various programs that share resources and services.

In this relationship, the client consumes resources from the server but does not necessarily share its own resources. The server may provide resources to multiple clients depending on the services that they provide. For example, a file server may serve computer files, and a web server may provide webpages to clients.

Typically, clients and servers communicate over a computer network, but they can also exist in the same system. Thus, communication is an integral part of the client-server model, which requires a standard structure to ensure consistency and efficiency.

What is REST?

REST is a software architectural style that outlines a set of guidelines in creating web services. These services are known as RESTful Web Services (RWS). It takes advantage of existing client-server systems and uses Hypertext Transfer Protocol (HTTP). Note that REST is not an entirely new technology but a pattern that aims to provide interoperability among systems on the Internet.

It is a resource-oriented model where web assets such as web pages and images are offered by servers to be consumed by clients. Servers can be any system that runs web services, and clients can be any application that uses those services as resources.

REST offers a simple architectural design and replaces much more complex models such as RPC, SOAP, or CORBA.

Click here to learn more about the History of APIs.

Constraints of REST Architecture

While there are no real REST “standards,” the architecture is governed by several constraints which are the major characteristics of RESTful web services.

These constraints are followed when developing APIs which allow diverse systems to communicate with each other.

Uniform Interface

Uniform interface is the key difference between a REST API and a non-REST API. Regardless of the client application, there should be a uniform way of interacting with the server and its resources.

The following guidelines further define Uniform Interface:

• Resource-based – Each resource is identified in client requests using URIs. For example, an HTTP GET request through the REST API.
• Manipulation of Resources Using Representations – Client application has representations of resources and can manipulate the resources using the representation such as update and delete (assuming it has the permission to do so). For example, a user record in a database may be represented by a user ID which is used by the client to delete or update the said record.
• Self-descriptive Messages – Each message from the client should contain enough information that will provide descriptions of how the server should process the message request.
• Hypermedia as the Engine of Application State (HATEOAS) – Messages between the client and the server contains links for each response so that the client application can discover other resources easily.

Client-Server

As already mentioned in the last section, REST applications are build over client-server architectures. The client and the server are independent of each other in terms of data storage and other internal technologies used. They can evolve independently without significant effects on the exposed resources.

Stateless

Stateless means the server should be able to process the request without having knowledge of previous requests. Additionally, the server should not store any information related to the session. As such, the request from the client must include all relevant information that will allow the server to fulfill the said request.

Cacheable

Every response from the server should include whether the response is cacheable or not. If so, it should also include how long the response can be cached on the client-side. A well-designed REST API should include some sort of caching, especially when the server offers a large set of data. It reduces client-server interaction which improves the application performance.

Layered System

A server can be composed of a layered system. For example, one server may deploy APIs, another server may store data, and another server may authenticate requests. These intermediary servers may interact with the client without the notice of the former. This improves system availability through load-balancing and shared caches.

Code on Demand

Code on demand is an optional feature of REST APIs. Servers can provide executable code to the client. For example, web services may serve client-side scripts such as Javascript to its clients.

Key Components of a RESTful API

Let’s dive deeper into REST by examining key parts of a RESTful API. Remember that an application programming interface or an API is a communication protocol or interface between two systems that simplify web application building.

While not a definitive guide, this section will introduce key parts of a REST API and the roles that they play in the REST architecture.

Resources

Because REST is a resource-oriented architecture, everything starts with resources. A resource is any form of data. For example, a customer record is a type of resource in REST architecture.

Additionally, a type of resource representation should be created to identify resources in the system. A common representation is an ID number. For example, customer ID that uniquely identifies a customer in a database.

Endpoint

Typically, a web service (server) is located using a URL such as https://somewebservice.com. An endpoint is an entry-point to a resource in a server using a URL. Depending on the structure of the APIs resources, naming conventions used in endpoints can be plural nouns. Consider the following endpoints:

The URL ending in /customers point to a list of customers in the server’s database. On the other hand /customers/123 refers to a specific customer with an ID of ‘123’ which leverages the hierarchical nature of URLs. A client application can send requests through these URLs.

Request Methods

With the resources and their corresponding endpoints in place, a client application can now interact with the server using HTTP request methods. By taking advantage of these HTTP actions, a client can create, read, update, or delete on the server subject to the permission granted by the REST API.

• GET – The HTTP GET method is used by the client to read or request for a representation of a resource from the server. A typical GET request may look something like:

POST – The HTTP POST method is used by the client to create or submit resources to the server. A POST request looks similar to a GET request with the addition of the resource to be added.

• PUT – The HTTP PUT method is used by the client to update existing resources on the server. Note that PUT can also create a resource if that resource does not exist yet on the server. PUT and POST have the same format. When the server encounters the same resource using PUT, it will update the said resource. On the other hand, when the same resource is found in POST, it will create a new resource with the same representation in the server every time (duplicates). For example, sending two POST requests containing “customerID”: “124” will create two records with identical IDs.
• DELETE – As the name implies, the HTTP DELETE method removes the identified resource from the server. A DELETE request may look something like:

Response Status Codes

HTTP also features response status codes that REST APIs use to indicate the result of a client’s request. It is a form of a server reply whether the client request is fulfilled or otherwise. Here are some of the most common HTTP response status codes and their meaning:

• 200 OK – Indicates a general success status code. It means the client’s request was fulfilled.
• 201 CREATED – Indicates created resource. Usually a reply to a PUT or POST request.
• 204 NO CONTENT – Indicates success without additional data in the response body. Typically a reply to DELETE or PUT.
• 400 BAD REQUEST – Indicates a general error in attempting the request.
• 403 FORBIDDEN – Indicates an error code when the client is not permitted to perform the requested operation.
• 404 NOT FOUND – Indicates the requested resource is not found.

There are more response status codes available and their usage depends on the developer of the API. However, the HTTP specifications are always followed (i.e., “200 OK” will always mean success).

REST API parts do not stop here. There are more building blocks needed to create a RESTful API from authentication to resource format. Depending on the web service being created, developers may need to add layers that will handle resource relationships, caching, and more.

REST Frameworks

Creating RESTful APIs rely on the requirements and specifications of the web service. At the enterprise level, the development of such API starts from scratch using the developers’ choice of technologies.

However, various REST frameworks aid developers in quickly getting their API development off the ground. These web application frameworks provide the necessary core technologies to create web services and REST APIs such as tools for resource management, endpoint definition, data formatting, and more. That means developers won’t have to code everything from scratch.

Two of the most popular frameworks are Django REST Framework and Flask-RESTful, which are both created using Python.

A Practical Example of REST API

To get a better idea of how a client-server communication happens through a REST API, let us send requests to an actual API.

In this tutorial, we will interact with JSONPlaceholder, which is a free online REST API. The JSONPlaceholder server houses fake and placeholder data and resources for prototyping and testing.

We will use Advanced REST Client to send requests and consume resources. ARC will let us examine data from JSONPlaceholder in JSON format.

First, download and install ARC on your machine. Then, head over to https://jsonplaceholder.typicode.com/. Examine the resources available under Resources. Routes lists all the HTTP methods supported by its REST API.

On ARC, choose GET under Method. Type https://jsonplaceholder.typicode.com under Host and /users under Path. Click Send.

You should receive a 200 OK response status along with a list of users in JSON format in the body of the response.

Next, let’s create a resource using the POST request. Under Method, choose POST. Change the path to /todos. Then, click the Body tab and add the following:

You should receive a 201 created response code that confirms the creation of the resource. If you want to further examine the header of the server’s response, click Details.

Note that due to limited space in the server, no new record is actually created in the database. However, the REST API mimics the response of a successful POST request. You can try sending a PUT or DELETE request by yourself. For more information, you can check the server’s guide.

Conclusion

If your needs don’t fall outside of CRUD, REST remains a fantastic pattern to use. At Aloi, we don’t necessarily see that ever changing, at least not so long as HTTP protocol remains a standard for software connectivity.

REST’s shortfalls are highlighted as the need to be able to do things that fall outside of this simple pattern (e.g. outside of the CRUD actions) begin to arise. Outside of CRUD, there’s no neat way to fit these extra actions in (at least not a method that everyone had agreed on).

At Aloi, we have supplemented REST with GraphQL to help build API integrations. We don’t compare REST to GraphQL as they are different technologies that should be used for different purposes. Some use cases might lend themselves to REST, others to GraphQL, and in the case of integrating API, we believe the best suggestion is to use them together.