Strong API design decisions reduce bugs, support faster frontend integration and make future scaling much easier. A good REST API is predictable: clients know where resources live, which HTTP methods to use, what status codes mean and how errors are returned.
I remember my first attempt at building an API. I treated it like a function call, ignored HTTP status codes and returned 200 OK for errors with a JSON body saying {"error": "Something went wrong"}. It made frontend integration harder than necessary.
This guide explains practical REST patterns for resource naming, status codes, validation, authentication, pagination, documentation, testing and reliability.
REST is an architectural style that defines a set of constraints for creating web services. RESTful APIs are:
REST is a strong choice when your API is resource-oriented, needs broad client support and benefits from standard HTTP behavior such as caching, status codes and retries.
Resources are the key entities your API exposes. Use nouns for resources and let HTTP methods describe the action.
# Good URI Design
GET /api/v1/users # Get all users
GET /api/v1/users/123 # Get specific user
POST /api/v1/users # Create new user
PUT /api/v1/users/123 # Update user
DELETE /api/v1/users/123 # Delete user
# Poor URI Design (Avoid)
GET /api/v1/getUsers
POST /api/v1/createUser
PUT /api/v1/updateUser/123
Understanding when to use each HTTP method is crucial:
| Method | Purpose | Idempotent | Safe |
|---|---|---|---|
| GET | Retrieve resource | Yes | Yes |
| POST | Create resource | No | No |
| PUT | Update resource | Yes | No |
| PATCH | Partial update | No | No |
| DELETE | Remove resource | Yes | No |
You might notice the "Idempotent" column in the table above. An idempotent operation can be applied multiple times without changing the result beyond the initial application.
Understanding this distinction is critical for building reliable APIs, especially when dealing with network retries.
Use appropriate status codes to communicate API responses. Avoid returning 200 OK for failed requests because clients then have to inspect every response body to know whether the request worked.
200 OK # Successful request
201 Created # Resource created
204 No Content # Successful request with no response body
400 Bad Request # Invalid client input
401 Unauthorized # Authentication required or invalid
403 Forbidden # Authenticated but not allowed
404 Not Found # Resource not found
409 Conflict # Request conflicts with current state
422 Unprocessable Entity # Valid JSON, but business validation failed
429 Too Many Requests # Rate limit exceeded
500 Server Error # Unexpected server error
Version APIs when clients outside your control depend on them. Mobile apps, partner integrations and public APIs need extra care because clients may not update immediately.
// URL-based versioning
https://api.example.com/v1/users
https://api.example.com/v2/users
// Header-based versioning
Accept: application/vnd.company.api+json;version=1
Implement robust security measures:
Content-Security-Policy.// JWT Authentication Example
const express = require('express');
const jwt = require('jsonwebtoken');
const helmet = require('helmet');
const cors = require('cors');
const app = express();
// Security middleware
app.use(helmet());
app.use(cors());
app.use(express.json());
app.post('/api/login', (req, res) => {
const { email, password } = req.body;
// Replace this with a real password check against your user store.
const user = findUserByEmail(email);
if (!user || !isValidPassword(user, password)) {
return res.status(401).json({ message: 'Invalid credentials' });
}
if (!process.env.JWT_SECRET) {
return res.status(500).json({ message: 'Authentication is not configured' });
}
const token = jwt.sign({ userId: user.id }, process.env.JWT_SECRET, {
expiresIn: '24h'
});
res.json({ token });
});
// Protected Route
app.get('/api/protected', authenticateToken, (req, res) => {
// Handle protected resource
});
Never hard-code a JWT secret in source control. Keep it in an environment variable, rotate it when team access changes and use a different secret for local, staging and production environments.
Also avoid storing sensitive data in tokens unless it is required. Tokens can be decoded by clients, so keep payloads small and non-sensitive.
Maintain consistent data formatting so clients do not need special handling for every endpoint.
// Good Response Format
{
"status": "success",
"data": {
"id": 123,
"name": "John Doe",
"email": "john@example.com"
},
"meta": {
"timestamp": "2024-02-28T08:00:00Z"
}
}
// Error Response Format
{
"status": "error",
"error": {
"code": "INVALID_INPUT",
"message": "Email is required",
"details": {...}
}
}
Implement efficient data handling for list endpoints. Without pagination, a successful endpoint can become slow or expensive as the database grows.
// Pagination Example
GET /api/users?page=2&limit=10
// Response
{
"data": [...],
"pagination": {
"current_page": 2,
"total_pages": 5,
"total_items": 48,
"items_per_page": 10
}
}
// Filtering Example
GET /api/users?role=admin&status=active
Let's create a simple Express.js API:
const express = require('express');
const app = express();
// Middleware
app.use(express.json());
// Sample data
const users = [];
// GET all users
app.get('/api/users', (req, res) => {
res.json({
status: 'success',
data: users
});
});
// POST new user
app.post('/api/users', (req, res) => {
const { name, email } = req.body;
// Validation
if (!name || !email) {
return res.status(400).json({
status: 'error',
error: {
message: 'Name and email are required'
}
});
}
const user = {
id: Date.now(),
name,
email
};
users.push(user);
res.status(201).json({
status: 'success',
data: user
});
});
This example is intentionally simple. A real API should store data in a database, validate email format, protect private endpoints and avoid using Date.now() as a long-term ID strategy.
// Postman Test Script Example
pm.test("Response status is 200", () => {
pm.response.to.have.status(200);
});
pm.test("Response has correct structure", () => {
const response = pm.response.json();
pm.expect(response).to.have.property('status');
pm.expect(response).to.have.property('data');
});
Use Swagger/OpenAPI for documentation:
openapi: 3.0.0
info:
title: User API
version: 1.0.0
paths:
/users:
get:
summary: Get all users
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
properties:
status:
type: string
data:
type: array
Protect your API from abuse and DoS attacks by limiting request frequency.
const rateLimit = require('express-rate-limit');
const limiter = rateLimit({
windowMs: 15 * 60 * 1000, // 15 minutes
max: 100, // limit each IP to 100 requests per windowMs
message: "Too many requests, please try again later."
});
// Apply to all API routes
app.use('/api/', limiter);
Improve performance by caching responses. You can use in-memory caching (like Redis) or HTTP caching headers.
const mcache = require('memory-cache');
const cache = (duration) => {
return (req, res, next) => {
const key = '__express__' + req.originalUrl;
const cachedBody = mcache.get(key);
if (cachedBody) {
res.send(cachedBody);
return;
}
res.sendResponse = res.send;
res.send = (body) => {
mcache.put(key, body, duration * 1000);
res.sendResponse(body);
};
next();
};
};
Some REST APIs include links in the response to help clients navigate available actions dynamically.
{
"id": 123,
"name": "John Doe",
"links": [
{ "rel": "self", "method": "GET", "href": "/api/users/123" },
{ "rel": "delete", "method": "DELETE", "href": "/api/users/123" },
{ "rel": "update", "method": "PUT", "href": "/api/users/123" }
]
}
REST and GraphQL solve different problems.
Choose REST for simplicity and standard tooling. Choose GraphQL for flexibility and efficiency in data retrieval.
Try implementing this simple Todo API:
const express = require('express');
const router = express.Router();
let todos = [];
// Get all todos
router.get('/todos', (req, res) => {
res.json(todos);
});
// Add new todo
router.post('/todos', (req, res) => {
if (!req.body.title) {
return res.status(400).json({ error: 'Title is required' });
}
const todo = {
id: Date.now(),
title: req.body.title,
completed: false
};
todos.push(todo);
res.status(201).json(todo);
});
// Mark todo as completed
router.patch('/todos/:id', (req, res) => {
const todo = todos.find(t => t.id === parseInt(req.params.id));
if (todo) {
todo.completed = req.body.completed;
res.json(todo);
} else {
res.status(404).json({ error: 'Todo not found' });
}
});
Building RESTful APIs is both design and engineering. Start simple, focus on consistency and improve based on real usage patterns and client feedback.
Use this checklist before you publish an API endpoint:
A small checklist like this prevents many support tickets after the API starts serving real users.
To make these ideas concrete, imagine an endpoint that creates a project for the authenticated user.
app.post('/api/v1/projects', authenticateUser, async (req, res) => {
const { name } = req.body;
if (!name || name.trim().length < 3) {
return res.status(400).json({
status: 'error',
error: {
code: 'INVALID_PROJECT_NAME',
message: 'Project name must be at least 3 characters long'
}
});
}
const project = await projectRepository.create({
ownerId: req.user.id,
name: name.trim()
});
return res.status(201).json({
status: 'success',
data: project
});
});
This endpoint demonstrates several REST habits at once: the route describes a resource, authentication happens before business logic, invalid input returns 400, successful creation returns 201 and the response shape stays predictable.
Before shipping this endpoint, I would test four cases: unauthenticated request, empty name, valid project creation and duplicate-name behavior if the product requires unique project names.
A RESTful API exposes resources through consistent URLs, uses standard HTTP methods, keeps requests stateless and communicates results with meaningful status codes and response bodies.
Use nouns for resources, such as /users, /projects or /orders. The HTTP method describes the action, such as GET /users, POST /users or DELETE /users/123.
Create a new version when a change would break existing clients. Adding optional fields usually does not require a new version, but removing fields, renaming fields or changing response shape often does.
No. JWT works well for some stateless APIs, but session cookies, OAuth or managed identity providers may be better depending on the client, security requirements and product architecture.
A good REST API is predictable before it is fancy. Clear resource names, consistent status codes, safe authentication and useful error messages will help your API more than adding extra endpoints too early.
Learning to code can feel confusing at first because there are many languages, tools, tutorials and opinions. One person says to start with Python, another recommends JavaScript and someone else says
Read MoreClean code pays long-term dividends on real software teams: fewer regressions, faster onboarding, easier reviews and simpler releases. It is not about making code look clever. It is about making futu
Read MoreBuilding your own software is one of the best ways to grow as a developer. It forces you to think beyond syntax and tutorials. You have to understand a problem, make tradeoffs, design data, write cod
Read More
