Node.js RESTful API
Understanding RESTful APIs
REST (Representational State Transfer) is an architectural style for designing networked applications that has become the standard for web services.
RESTful APIs provide a flexible, lightweight way to integrate applications and enable communication between different systems.
Core Concepts:
- Resources: Everything is a resource (user, product, order)
- Representations: Resources can have multiple representations (JSON, XML, etc.)
- Stateless: Each request contains all necessary information
- Uniform Interface: Consistent way to access and manipulate resources
RESTful APIs use HTTP requests to perform CRUD operations (Create, Read, Update, Delete) on resources, which are represented as URLs.
REST is stateless, meaning each request from a client to a server must contain all the information needed to understand and process the request.
Unlike SOAP or RPC, REST is not a protocol but an architectural style that leverages existing web standards like HTTP, URI, JSON, and XML.
Core REST Principles
Understanding these principles is crucial for designing effective RESTful APIs.
They ensure your API is scalable, maintainable, and easy to use.
Key Principles in Practice:
- Resource-Based: Focus on resources rather than actions
- Stateless: Each request is independent and self-contained
- Cacheable: Responses define their cacheability
- Uniform Interface: Consistent resource identification and manipulation
- Layered System: Client doesn't need to know about the underlying architecture
The core principles of REST architecture include:
- Client-Server Architecture: Separation of concerns between the client and the server
- Statelessness: No client context is stored on the server between requests
- Cacheability: Responses must define themselves as cacheable or non-cacheable
- Layered System: A client cannot tell whether it is connected directly to the end server
- Uniform Interface: Resources are identified in requests, resources are manipulated through representations, self-descriptive messages, and HATEOAS (Hypertext As The Engine Of Application State)
HTTP Methods and Their Usage
RESTful APIs use standard HTTP methods to perform operations on resources.
Each method has specific semantics and should be used appropriately.
Idempotency and Safety:
- Safe Methods: GET, HEAD, OPTIONS (should not modify resources)
- Idempotent Methods: GET, PUT, DELETE (multiple identical requests = same effect as one)
- Non-Idempotent: POST, PATCH (may have different effects with multiple calls)
Always use the most specific method that matches your operation's intent.
| Method | Action | Example |
|---|---|---|
| GET | Retrieve resource(s) | GET /api/users |
| POST | Create a new resource | POST /api/users |
| PUT | Update a resource completely | PUT /api/users/123 |
| PATCH | Update a resource partially | PATCH /api/users/123 |
| DELETE | Delete a resource | DELETE /api/users/123 |
Example: Using Different HTTP Methods
const express = require('express');
const app = express();
// Middleware for parsing JSON
app.use(express.json());
let users = [
{ id: 1, name: 'John Doe', email: 'john@example.com' },
{ id: 2, name: 'Jane Smith', email: 'jane@example.com' }
];
// GET - Retrieve all users
app.get('/api/users', (req, res) => {
res.json(users);
});
// GET - Retrieve a specific user
app.get('/api/users/:id', (req, res) => {
const user = users.find(u => u.id === parseInt(req.params.id));
if (!user) return res.status(404).json({ message: 'User not found' });
res.json(user);
});
// POST - Create a new user
app.post('/api/users', (req, res) => {
const newUser = {
id: users.length + 1,
name: req.body.name,
email: req.body.email
};
users.push(newUser);
res.status(201).json(newUser);
});
// PUT - Update a user completely
app.put('/api/users/:id', (req, res) => {
const user = users.find(u => u.id === parseInt(req.params.id));
if (!user) return res.status(404).json({ message: 'User not found' });
user.name = req.body.name;
user.email = req.body.email;
res.json(user);
});
// DELETE - Remove a user
app.delete('/api/users/:id', (req, res) => {
const userIndex = users.findIndex(u => u.id === parseInt(req.params.id));
if (userIndex === -1) return res.status(404).json({ message: 'User not found' });
const deletedUser = users.splice(userIndex, 1);
res.json(deletedUser[0]);
});
app.listen(8080, () => {
console.log('REST API server running on port 8080');
});
RESTful API Structure and Design
A well-designed API follows consistent patterns that make it intuitive and easy to use. Good API design is crucial for developer experience and long-term maintainability.
Design Considerations:
- Resource Naming: Use nouns, not verbs (e.g.,
/usersnot/getUsers) - Pluralization: Use plural for collections (
/users/123not/user/123) - Hierarchy: Nest resources to show relationships (
/users/123/orders) - Filtering/Sorting: Use query parameters for optional operations
- Versioning Strategy: Plan for API versioning from the start (e.g.,
/v1/usersvs/v2/users).
A well-structured API follows these conventions:
- Use nouns for resources: /users, /products, /orders (not /getUsers)
- Use plurals for collections: /users instead of /user
- Nest resources for relationships: /users/123/orders
- Use query parameters for filtering: /products?category=electronics&min_price=100
- Keep URLs consistent: Choose a convention (kebab-case, camelCase) and stick to it
Example: Well-structured API Routes
// Good API structure
app.get('/api/products', getProducts);
app.get('/api/products/:id', getProductById);
app.get('/api/products/:id/reviews', getProductReviews);
app.get('/api/users/:userId/orders', getUserOrders);
app.post('/api/orders', createOrder);
// Filtering and pagination
app.get('/api/products?category=electronics&sort=price&limit=10&page=2');
Building REST APIs with Node.js and Express
Node.js with Express.js provides an excellent foundation for building RESTful APIs.
The following sections outline best practices and patterns for implementation.
Key Components:
- Express Router: For organizing routes
- Middleware: For cross-cutting concerns
- Controllers: For handling request logic
- Models: For data access and business logic
- Services: For complex business logic
Express.js is the most popular framework for building REST APIs in Node.js.
Here's a basic project structure:
Project Structure
- app.js # Main application file
- routes/ # Route definitions
- users.js
- products.js
- controllers/ # Request handlers
- userController.js
- productController.js
- models/ # Data models
- User.js
- Product.js
- middleware/ # Custom middleware
- auth.js
- validation.js
- config/ # Configuration files
- db.js
- env.js
- utils/ # Utility functions
- errorHandler.js
Example: Setting Up Express Router
// routes/users.js
const express = require('express');
const router = express.Router();
const { getUsers, getUserById, createUser, updateUser, deleteUser } = require('../controllers/userController');
router.get('/', getUsers);
router.get('/:id', getUserById);
router.post('/', createUser);
router.put('/:id', updateUser);
router.delete('/:id', deleteUser);
module.exports = router;
// app.js
const express = require('express');
const app = express();
const userRoutes = require('./routes/users');
app.use(express.json());
app.use('/api/users', userRoutes);
app.listen(8080, () => {
console.log('Server is running on port 8080');
});
Controllers and Models
Separating concerns between routes, controllers, and models improves code organization and maintainability:
Example: Controller Implementation
// controllers/userController.js
const User = require('../models/User');
const getUsers = async (req, res) => {
try {
const users = await User.findAll();
res.status(200).json(users);
} catch (error) {
res.status(500).json({ message: 'Error retrieving users', error: error.message });
}
};
const getUserById = async (req, res) => {
try {
const user = await User.findById(req.params.id);
if (!user) {
return res.status(404).json({ message: 'User not found' });
}
res.status(200).json(user);
} catch (error) {
res.status(500).json({ message: 'Error retrieving user', error: error.message });
}
};
const createUser = async (req, res) => {
try {
const user = await User.create(req.body);
res.status(201).json(user);
} catch (error) {
res.status(400).json({ message: 'Error creating user', error: error.message });
}
};
module.exports = { getUsers, getUserById, createUser };
API Versioning
Versioning helps you evolve your API without breaking existing clients.
Common approaches include:
- URI Path Versioning: /api/v1/users
- Query Parameter: /api/users?version=1
- Custom Header: X-API-Version: 1
- Accept Header: Accept: application/vnd.myapi.v1+json
Example: URI Path Versioning
const express = require('express');
const app = express();
// Version 1 routes
const v1UserRoutes = require('./routes/v1/users');
app.use('/api/v1/users', v1UserRoutes);
// Version 2 routes with new features
const v2UserRoutes = require('./routes/v2/users');
app.use('/api/v2/users', v2UserRoutes);
app.listen(8080);
Request Validation
Always validate incoming requests to ensure data integrity and security.
Libraries like Joi or express-validator can help:
Example: Request Validation with Joi
const express = require('express');
const Joi = require('joi');
const app = express();
app.use(express.json());
// Validation schema
const userSchema = Joi.object({
name: Joi.string().min(3).required(),
email: Joi.string().email().required(),
age: Joi.number().integer().min(18).max(120)
});
app.post('/api/users', (req, res) => {
// Validate request body
const { error } = userSchema.validate(req.body);
if (error) {
return res.status(400).json({ message: error.details[0].message });
}
// Process valid request
// ...
res.status(201).json({ message: 'User created successfully' });
});
app.listen(8080);
Error Handling
Implement consistent error handling to provide clear feedback to API consumers:
Example: Centralized Error Handling
// utils/errorHandler.js
class AppError extends Error {
constructor(statusCode, message) {
super(message);
this.statusCode = statusCode;
this.status = `${statusCode}`.startsWith('4') ? 'fail' : 'error';
this.isOperational = true;
Error.captureStackTrace(this, this.constructor);
}
}
module.exports = { AppError };
// middleware/errorMiddleware.js
const errorHandler = (err, req, res, next) => {
err.statusCode = err.statusCode || 500;
err.status = err.status || 'error';
// Different error responses for development and production
if (process.env.NODE_ENV === 'development') {
res.status(err.statusCode).json({
status: err.status,
message: err.message,
stack: err.stack,
error: err
});
} else {
// Production: don't leak error details
if (err.isOperational) {
res.status(err.statusCode).json({
status: err.status,
message: err.message
});
} else {
// Programming or unknown errors
console.error('ERROR 💥', err);
res.status(500).json({
status: 'error',
message: 'Something went wrong'
});
}
}
};
module.exports = { errorHandler };
// Usage in app.js
const { errorHandler } = require('./middleware/errorMiddleware');
const { AppError } = require('./utils/errorHandler');
// This route throws a custom error
app.get('/api/error-demo', (req, res, next) => {
next(new AppError(404, 'Resource not found'));
});
// Error handling middleware (must be last)
app.use(errorHandler);
API Documentation
Good documentation is essential for API adoption.
Tools like Swagger/OpenAPI can automatically generate documentation from code:
Example: Swagger Documentation
const express = require('express');
const swaggerJsDoc = require('swagger-jsdoc');
const swaggerUi = require('swagger-ui-express');
const app = express();
// Swagger configuration
const swaggerOptions = {
definition: {
openapi: '3.0.0',
info: {
title: 'User API',
version: '1.0.0',
description: 'A simple Express User API'
},
servers: [
{
url: 'http://localhost:8080',
description: 'Development server'
}
]
},
apis: ['./routes/*.js'] // Path to the API routes folders
};
const swaggerDocs = swaggerJsDoc(swaggerOptions);
app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocs));
/**
* @swagger
* /api/users:
* get:
* summary: Returns a list of users
* description: Retrieve a list of all users
* responses:
* 200:
* description: A list of users
* content:
* application/json:
* schema:
* type: array
* items:
* type: object
* properties:
* id:
* type: integer
* name:
* type: string
* email:
* type: string
*/
app.get('/api/users', (req, res) => {
// Handler implementation
});
app.listen(8080);
Testing APIs
Testing is critical for API reliability.
Use libraries like Jest, Mocha, or Supertest:
Example: API Testing with Jest and Supertest
// tests/users.test.js
const request = require('supertest');
const app = require('../app');
describe('User API', () => {
describe('GET /api/users', () => {
it('should return all users', async () => {
const res = await request(app).get('/api/users');
expect(res.statusCode).toBe(200);
expect(Array.isArray(res.body)).toBeTruthy();
});
});
describe('POST /api/users', () => {
it('should create a new user', async () => {
const userData = {
name: 'Test User',
email: 'test@example.com'
};
const res = await request(app)
.post('/api/users')
.send(userData);
expect(res.statusCode).toBe(201);
expect(res.body).toHaveProperty('id');
expect(res.body.name).toBe(userData.name);
});
it('should validate request data', async () => {
const invalidData = {
email: 'not-an-email'
};
const res = await request(app)
.post('/api/users')
.send(invalidData);
expect(res.statusCode).toBe(400);
});
});
});
Best Practices Summary
- Follow REST principles and use appropriate HTTP methods
- Use consistent naming conventions for endpoints
- Structure your API logically with resource-based URLs
- Return appropriate status codes in responses
- Implement proper error handling with clear messages
- Use pagination for large data sets
- Version your API to maintain backward compatibility
- Validate all input to prevent security issues
- Document your API thoroughly
- Write comprehensive tests to ensure reliability
- Use HTTPS for all production APIs
- Implement rate limiting to prevent abuse
