The Art and Science behind REST APIs

REST stands for REpresentational State Transfer

REST is a software architectural style that defines a set of rules to be used for creating web services. Web services which follow the REST architectural style are known as RESTful web services.

It allows requesting systems to access and manipulate web resources by using a uniform and predefined set of rules. Interaction in REST based systems happen through internet's Hypertext Transfer Protocol (HTTP).

A Restful system consists of a -

Client - Who requests for the resources

Server - Who has the resources

It is important to create your REST API according to industry standards which results in ease of development and increase client adoption.

RESTful system constraints

There are 6 constraints that a service should follow -

• Uniform Interface
• Stateless
• Cacheable
• Client-Server
• Layered System
• Code on Demand

The only optional constraint of REST architecture is code on demand. If a service violates any other constraint, it cannot strictly be referred to as RESTful.

Now, let us discuss these constraints one by one -

1. Uniform Interface -

It is a key constraint that differentiate between a REST API and Non-REST API. It suggests that there should be an uniform way of interacting with a given server irrespective of device or type of application (website, mobile app).

4 guiding principles of Uniform Interface are -

Resource-Based - While dealing with restful service you deal with resource or series of resources or you can say that you are dealing with nouns. So, you should be able to identify a resource through a URI.
example : api/users.

Manipulation of Resources Through Representations - Client has representation of resource and it contains enough information to modify or delete the resource on the server, provided it has permission to do so. example : you usually get a user id when you request for a list of users and you can then use that id to delete or modify that particular user.

Self-descriptive Messages - Each message includes enough information to describe how to process the message so that server can easily analyse the request.

Hypermedia as the Engine of Application State (HATEOAS) - You need to include links for each response so that client can discover other resources easily.

2. Stateless -

It means that the necessary state to handle the request is contained within the request itself and server would not store anything related to the session. In REST, the client must include all information for the server to fulfil the request whether as a part of query params, headers or URI.

Statelessness enables greater scalability since the server does not have to maintain, update or communicate that session state.

There is a drawback of this also - Client need to send too much data to the server so it reduces the scope of network optimisation and requires more bandwidth.

3. Cacheable -

Every response should include whether the response is cacheable or not and for how much duration responses can be cached at the client side.

Client will return the data from its cache for any subsequent request and there would be no need to send the request again to the server. A well-managed caching partially or completely eliminates some client–server interactions, further improving scalability and performance.

But sometime there are chances that user may receive stale data.

4. Client-Server -

REST application should have a client-server architecture.

A Client is someone who is requesting resources and are not concerned with data storage, which remains internal to each server, and server is someone who holds the resources and are not concerned with the user interface or user state.

They can evolve independently. Client doesn't need to know anything about business logic and server doesn't need to know anything about frontend UI.

5. Layered system -

An application architecture needs to be composed of multiple layers. Each layer doesn't know any thing about any layer other than that of immediate layer and there can be lot of intermediate servers between client and the end server.

Intermediary servers may improve system scalability by enabling load-balancing and by providing shared caches.

6. Code on demand -

This feature is an optional one.

According to this, servers can also provide executable code to the client. Examples of this may include compiled components such as Java applets and client-side scripts such as JavaScript.

REST API rules -

There are certain rules which should be kept in mind while creating REST API endpoints.

REST is resource based or noun based instead of action or verb based. It means that a URI of a REST API should always end with a noun.
example : /api/users is a good example, but /api?type=users is a bad example of creating a REST API.

HTTP verbs are used to identify the action. Some of the HTTP verbs are - GET, PUT, POST, DELETE, UPDATE, PATCH.

A web application should be organised into resources like users and then uses HTTP verbs like - GET, PUT, POST, DELETE to modify those resources. And as a developer it should be clear that what needs to be done just by looking at the endpoint and HTTP method used.
Refer to the table below to know more -

Always use plurals in URL to keep an API URI consistent throughout the application.

Send a proper HTTP code to indicate a success or error status.

HTTP verbs -

Some of the common HTTP methods/verbs are described below -

GET - Retrieves one or more resources identified by the request URI and we can cache the information we receive.

POST - Create a resource from the submission of a request and response is not cacheable in this case. This method is unsafe if no security is applied to the endpoint as it would allow anyone to create a random resource by submission.

PUT - You can update an existing resource on the server specified by the request URI.

DELETE - You can delete an existing resource on the server specified by the request URIWe should always return an appropriate HTTP status for every request.

GET, PUT, DELETE methods are also known as Idempotent methods - Applying an operation once or applying it multiple times has the same effect. example : If you delete any resource from the server and it succeeds with 200 OK and if you try again to delete that resource than you should get an error message saying 410 GONE.

Thanks for reading :)

Happy Learning