Understanding REST APIs
A Complete Guide to Resources, HTTP Methods, and Clean API Design
Introduction
Modern web applications rely heavily on communication between the frontend (client) and backend (server). This communication happens through APIs. One of the most widely used architectural styles for building APIs is REST.
REST APIs are simple, scalable, and widely adopted in real-world systems. Understanding REST is essential for backend development, full-stack development, and even frontend integration.
This blog explains REST APIs from the ground up, focusing on concepts, practical examples, and clean design principles.
What REST API Means
REST stands for Representational State Transfer. It is an architectural style used to design network-based applications.
A REST API allows a client (such as a browser or mobile app) to communicate with a server using standard HTTP protocols.
Key Idea
A REST API is essentially a structured way for a client and server to communicate.
The client sends a request
The server processes it
The server sends back a response
Example
When you open a website and it loads user data:
The frontend sends a request to the server
The server returns user data in JSON format
This interaction is handled through REST APIs.
APIs as Communication Between Client and Server
To understand REST, think of APIs as a bridge between two systems.
Flow of Communication
Client sends a request (e.g., “Give me all users”)
Server receives and processes the request
Server responds with data (usually JSON)
Example
GET /users
Response:
[
{ "id": 1, "name": "John" },
{ "id": 2, "name": "Jane" }
]
This simple request-response cycle forms the foundation of REST APIs.
Resources in REST Architecture
In REST, everything is treated as a resource.
A resource is any data that can be accessed or manipulated.
Examples of Resources
Users
Products
Orders
Posts
Each resource is identified by a URL (endpoint).
Example
/users
/products
/orders
Important Concept
/users→ collection of users/users/1→ specific user
REST focuses on nouns (resources) rather than verbs.
HTTP Methods (Core of REST)
REST APIs use standard HTTP methods to perform operations on resources.
1. GET (Read Data)
Used to fetch data from the server.
GET /users
GET /users/1
Does not modify data
Safe and idempotent
2. POST (Create Data)
Used to create a new resource.
POST /users
Request Body:
{
"name": "Alice"
}
Creates a new user
Not idempotent
3. PUT (Update Data)
Used to update an existing resource.
PUT /users/1
Replaces the entire resource
Idempotent (same request → same result)
4. DELETE (Remove Data)
Used to delete a resource.
DELETE /users/1
Removes the user
Idempotent
CRUD vs HTTP Methods Mapping
Create → POST
Read → GET
Update → PUT
Delete → DELETE
This mapping is fundamental in REST API design.
Status Codes Basics
Status codes are returned by the server to indicate the result of a request.
Common Status Codes
| Code | Meaning |
|---|---|
| 200 | OK (success) |
| 201 | Created |
| 400 | Bad Request |
| 401 | Unauthorized |
| 404 | Not Found |
| 500 | Internal Server Error |
Examples
200 OK→ Data fetched successfully201 Created→ Resource created successfully404 Not Found→ Resource does not exist
Status codes help clients understand what happened without reading the full response.
Designing Routes Using REST Principles
Good API design is about clarity and consistency.
Rules for Clean REST Routes
Use nouns, not verbs
❌
/getUsers✅
/users
Use plural names
/users,/products
Use proper HTTP methods
GET → fetch
POST → create
Use hierarchical structure
/users/1/orders
Example Resource: Users
Let’s design a complete REST API for a users resource.
Get All Users
GET /users
Get Single User
GET /users/1
Create User
POST /users
Update User
PUT /users/1
Delete User
DELETE /users/1
REST Request-Response Lifecycle
Client → Request → Server → Process → Response → Client
Step-by-Step
Client sends HTTP request
Server receives it
Server processes logic (DB, validation, etc.)
Server sends response with status code
Client handles the response
Real-World Example (Node.js Style)
app.get("/users", (req, res) => {
res.status(200).json([{ id: 1, name: "John" }]);
});
app.post("/users", (req, res) => {
res.status(201).json({ message: "User created" });
});
Common Mistakes to Avoid
Using verbs in routes (
/createUser)Ignoring status codes
Mixing responsibilities in endpoints
Not following consistent naming
Benefits of REST APIs
Simple and easy to understand
Scalable and stateless
Works with any frontend (web, mobile)
Standardized communication
Conclusion
REST APIs provide a clean and structured way for clients and servers to communicate. By treating data as resources and using standard HTTP methods, developers can build scalable and maintainable systems.
Understanding REST is a fundamental step in backend development. Once mastered, it becomes easier to design APIs, integrate services, and build full-stack applications efficiently.
The next step after REST would be exploring authentication, middleware, and advanced API patterns to build production-level systems.