Rest & Restfulness API Design Principles

Rohit Sharma — Thu, 18 Jun 2026 01:43:54 +0000

Representational State Transfer is an architectural style used for designing the network applications. Instead of relying on complex protocols REST relies on standard web protocols like HTTP to enable communication between clients and server.

If Definition seems complex to you, no worries let's breakdown the word
REST = Representation State Transfer

Suppose you have a user resource:

/users/7

This actual resource, exists on the server i.e. database row containing all the information about user with id 7.

REPRESENTATION The server doesn't send the actual database row. It sends just a representation of the resource.

{
 "id":7,
 "name":"Rohit"
}

This JSON is a representation of the user's current state.

STATE TRANSFER When the client requests

GET users/7

The server transfers representation of this resource's state to the client.

   Server State
        ⬇️
JSON Representation
        ⬇️
Transferred over HTTP
        ⬇️
      Client

That's where the term Representational state transfer comes from.

Main Idea behind REST: It operates on stateless communication which means that each request from client contains all the necessary information and server does not store any session data between requests. This makes REST very scalable, reliable and easy to implement.

Why REST matters?

Simplicity & Scalability: Rest is build on standard HTTP protocols like GET, PUT, POST and DELETE making it easy to understand and implement. Because REST follow stateless architecture it scales efficiently, allowing multiple servers to handle requests without maintaining session data.
Interoperability: REST APIs are platform independent which means they can be consumed by clients running on different devices, different Operating Systems and implemented in different programming languages. Whether its a mobile application or web application, REST can be used everywhere.
Efficiency: By leveraging caching REST can introduce lower latency which contribute towards enhancing performance.

app.get(/product/:id, async(req,res) =>{
  product = await productService.getProduct(req.params.id);
  res.set('Cache-Control', 'public, max-age=300');  //this tells clients, browsers, CDNs, reverse proxies & API Gateways: You may cache this response for 300 seconds
  res.json(product);
})

REST's cachebility constraint is typically implemented by sending HTTP cache headers such as Cache-Control, ETag or expires. These headers allow clients to cache responses, reducing the latency and backend loads.

RESTful API Design Principles

Not every API using HTTP is RESTful, A RESTful API is an API that follows REST principles correctly. So, below are the design principles of a perfect REST API:

1.Resource-Based URLs: Resources should be nouns, not verbs.

❌BAD

GET /getUsers
POST /createUser
DELETE /deleteUser/101

✅GOOD

GET /users
POST /users
DELETE /users/101

2.Use HTTP methods properly

GET    /users       -> Fetch users
POST   /users       -> Create user
PUT    /users/101   -> Replace user
PATCH  /users/101   -> Update user
DELETE /users/101   -> Delete user

3.Statelessness: Every request should contain all information needed. Server should not remember previous requests.

GET /orders
Authorization: Bearer JWT_TOKEN

//The JWT carries user identity. Server doesn't need session memory.

4.Client-Server Separation: Frontend and backend are independent. Frontend can change without changing backend
5.Cacheable Responses: Frequently accessed data can be cached, which eventually reduces latency and improves performance.

Example of perfect RESTful User API

GET    /users
GET    /users/101
POST   /users
PUT    /users/101
PATCH  /users/101
DELETE /users/101

This is considered RESTful because:

✅ Resources are nouns
✅ Correct HTTP methods used
✅ Stateless
✅ Consistent URL design

DEV Community: Rohit Sharma

Rest & Restfulness API Design Principles