what is a REST API?

REST stands for Representational State Transfer and is a standard set of architectural principles/guidelines that has some specific constraints which we’ll be digging deeper into later. This set of guidelines that were invented in 2000 led to unveiling the true potential of web APIs which changed the entire API landscape. REST API is an architectural style for building web services that interact via an HTTP protocol.

Before diving into REST APIs, Let’s just be clear about what is HTTP and what is REST architecture.

HTTP protocol

HTTP is a client-server protocol that is used to transfer hypermedia resources such as HTML documents, images, and even videos from a server to the recipient. Usually, the recipient is a web browser that initiates the requests while the server is the one that handles the requests and sends responses back. In a nutshell, what happens when we are loading web pages from a web browser is that an HTTP request is sent across the network to the web application server & then the server sends back an HTTP response with the hypertext document which we at the end get to see as a web page.

REST architecture

In software engineering, there’s an architectural style called ‘SOA’ (Service-Oriented Architecture) that supports building software systems in a service-oriented manner. This architecture defines a way to build software components re-usable via interfaces. These interfaces utilize a common standard communication protocol(Ex: HTTP) in such a way that these service interfaces can be integrated into new applications easily without any deep integration. Depending on the type of API, the choice of protocol changes.

REST and SOAP are two such popular web API services that follow the SOA architecture but with different approaches. By the way, since our main focus is on REST APIs, let’s dive deeper into the REST architecture.

REST APIs use HTTP methods explicitly

In HTTP protocol, there are multiple methods like PUT, PATCH, DELETE, OPTION, and a few more, in addition to the most often used GET & POST methods. But before the REST architecture was introduced, we were not getting the best use of all these methods in the HTTP protocol. REST enforces the use of all available methods in the HTTP protocol in a handy way as they were meant to be used. (we can create REST APIs for all CRUD operations using these different methods in HTTP protocol)

In simple terms, HTTP is just the protocol while REST API is a way that HTTP protocol could be used to get done the same task and much more.

Constraints (principles of a REST API)

REST defines five major architectural constraints which make any web API a REST API.

• Uniform Interface

The API should be self-descriptive in a way that the target audience who uses can get a high-level understanding of what happens from that API. The URI of the API should be clear enough to determine what resource is handled by the specific API.

• Stateless

Basically, to perform a particular request, you need to provide everything that needs to have for that request to perform without depending on the data being passed in the previous request. Because HTTP doesn’t save the state of the client agent. So no previous session details are saved for later usage.

Ex: When login into a system that is doing an access token-based authentication to authenticate the user, you can’t expect that the authentication will happen automatically when the user logs in for the 2nd time hoping that the state of the previous request is still existing. Since HTTP is a stateless protocol, for the server to recognize the same logged-in user, you need to pass that token with every request. In simple words, the request should be self-sufficient itself.

• Cacheable

Caching is a very important feature of REST APIs which can be done to increase the API performance. Any HTTP request is usually cacheable. If u want to cache details of a particular HTTP request, you’re cable of doing that by following the necessary steps.

• Client-Server

REST applications should have a client-server architecture. The user interface of the application should be separated from the data storage so each part can be scaled individually.

• Layered system

A REST API can be created on top of a layered system architecture where you can deploy the API on one server, store data on another server, and authenticate requests on another server. The client doesn’t see the underlying layers or the complexities of the service. The client only deals with the resource URI and the verb.

Designing a REST API

An API endpoint contains a domain name (host), resource name, version number(optional), and any parameter if required according to the operation.

Example of how an end-point should look like: https://abccompany.com/products/

The URI of an API is everything that comes after the domain name(hostname).

When designing a REST API, resource-naming should be done very carefully. The name and the structure of the URI should convey the meaning or the purpose of the API to users/developers who use the API to perform a certain operation.

REST services use HTTP verbs to perform different operations on the same resource. REST services are resource-based but not action-based. Therefore, make sure to use nouns for resources instead of verbs which is a good practice. Also, the most common and highly recommended way is to use the plural name of the resource when designing API for a particular resource. so that we can keep the URI of the API consistent across all HTTP methods.

Ex: Assume a scenario where you want to design an API to get(retrieve) all products from a products database and another API to insert details of a new product to the same database.

Now it is clear that one is a GET request and the other one is a POST request.

Now you can create two endpoints for this as below:

GET: /products/
POST: /products/addNewProduct/              

But don’t do this. The GET method itself is sufficient to say that it is retrieving something. Similarly, the POST method itself conveys that this endpoint can be used to insert something. So no need to add more verbs like ‘addNewProduct’ to describe it further.

Just make it simpler and readable as follows;

GET: /products/
POST: /products/                              

Also, let’s say that you need to retrieve details of a specific product, update a specific product, and delete a specific product. Then just passing the ID of the product as a parameter to the same end point as below while using the correct HTTP verb is enough. because the HTTP verb is sufficient to describe the action.

GET: /products/{id}
PUT: /products/{id}
DELETE: /products/{id}

We just discussed some good practices to follow when designing API endpoints.

Any REST API request includes four essential parts;

• An HTTP method (which describes what to be done with a resource)
• An end-point (Ex: https://abc-site.com/products )
• Header
• Body

Usually GET, DELETE requests not supposed to have Request body. But there are some exceptions. (There can be servers which supports it). However, any response can have a body.

With the response body, you can also send a HTTP status code to the client to indicate what happened on the request.

Response status codes are grouped into five categories as below.

1. Informational responses (100–199)
2. Successful responses (200–299)
3. Redirection messages (300–399)
4. Client error responses (400–499)
5. Server error responses (500–599)

It’s up to you to choose the correct status code from this list of codes to send with the API response to give a quick and concise idea to the client about how the server responded to that specific client’s request.

I hope it’s time to end this blog post from here without making you overwhelmed with more details. I have just discussed what simply a REST API is and what to consider when designing a good REST API. Go search more and start building your own APIs. Trust me it’s gonna be fun. See you soon with a new blog post. Cheers!