Building RESTful APIs with Express

Introduction to RESTful APIs

RESTful APIs (Representational State Transfer) provide a standardized approach for creating web services that are scalable, maintainable, and easy to understand. Express makes it remarkably simple to implement RESTful principles in your applications.

REST Architectural Principles

REST is built on several key principles that guide API design:

Key Principles

• Resource-Based: Everything is a resource, identified by a unique URI
• Stateless: Each request contains all the information needed to process it
• Uniform Interface: Consistent methods for interacting with resources
• Client-Server Architecture: Separation of concerns between client and server
• Layered System: Client can't tell if it's connected directly to the end server
• Cacheable: Responses explicitly state if they can be cached

Express for RESTful APIs

Express provides a robust framework for building RESTful APIs with minimal code:

const express = require('express');
const app = express();

// Middleware for parsing JSON bodies
app.use(express.json());

// Resources (in a real app, these would come from a database)
let users = [
  { id: 1, name: 'Alice', email: 'alice@example.com' },
  { id: 2, name: 'Bob', email: 'bob@example.com' }
];

// GET all users
app.get('/api/users', (req, res) => {
  res.status(200).json(users);
});

// GET single user
app.get('/api/users/:id', (req, res) => {
  const id = parseInt(req.params.id);
  const user = users.find(user => user.id === id);
  
  if (!user) {
    return res.status(404).json({ message: 'User not found' });
  }
  
  res.status(200).json(user);
});

// POST new user
app.post('/api/users', (req, res) => {
  const { name, email } = req.body;
  
  if (!name || !email) {
    return res.status(400).json({ message: 'Name and email are required' });
  }
  
  const newUser = {
    id: users.length + 1,
    name,
    email
  };
  
  users.push(newUser);
  res.status(201).json(newUser);
});

// PUT (update) user
app.put('/api/users/:id', (req, res) => {
  const id = parseInt(req.params.id);
  const { name, email } = req.body;
  
  const userIndex = users.findIndex(user => user.id === id);
  
  if (userIndex === -1) {
    return res.status(404).json({ message: 'User not found' });
  }
  
  const updatedUser = {
    ...users[userIndex],
    name: name || users[userIndex].name,
    email: email || users[userIndex].email
  };
  
  users[userIndex] = updatedUser;
  res.status(200).json(updatedUser);
});

// DELETE user
app.delete('/api/users/:id', (req, res) => {
  const id = parseInt(req.params.id);
  
  const userIndex = users.findIndex(user => user.id === id);
  
  if (userIndex === -1) {
    return res.status(404).json({ message: 'User not found' });
  }
  
  users.splice(userIndex, 1);
  res.status(204).send();
});

app.listen(3000, () => {
  console.log('API server running on port 3000');
});
                

HTTP Methods and their RESTful Uses

HTTP methods map directly to CRUD operations in a RESTful API:

// PATCH (partial update) user
app.patch('/api/users/:id', (req, res) => {
  const id = parseInt(req.params.id);
  const updates = req.body;
  
  const userIndex = users.findIndex(user => user.id === id);
  
  if (userIndex === -1) {
    return res.status(404).json({ message: 'User not found' });
  }
  
  // Only update the fields provided in the request
  users[userIndex] = { ...users[userIndex], ...updates };
  
  res.status(200).json(users[userIndex]);
});
                

URL Structure and Resource Naming

Well-designed resource naming is crucial for creating intuitive and maintainable APIs:

Best Practices

• Use Nouns, Not Verbs: Resources should be named with nouns (e.g., /users not /getUsers)
• Use Plurals for Collections: Collections of resources should be plural (/users not /user)
• Use Hierarchical Relationships: Represent relationships in the URL path (/users/42/posts)
• Keep URLs Simple and Predictable: Prefer /users/42 over /user-management/find/42
• Use Query Parameters for Filtering/Sorting: /products?category=electronics&sort=price
• Use Hyphens for Multi-Word Resources: /blog-posts is easier to read than /blogposts

// Get all posts by a specific user
app.get('/api/users/:userId/posts', (req, res) => {
  const userId = parseInt(req.params.userId);
  const userPosts = posts.filter(post => post.userId === userId);
  
  res.status(200).json(userPosts);
});

// Get a specific post by a specific user
app.get('/api/users/:userId/posts/:postId', (req, res) => {
  const userId = parseInt(req.params.userId);
  const postId = parseInt(req.params.postId);
  
  const post = posts.find(p => p.userId === userId && p.id === postId);
  
  if (!post) {
    return res.status(404).json({ message: 'Post not found' });
  }
  
  res.status(200).json(post);
});

// Create a new post for a user
app.post('/api/users/:userId/posts', (req, res) => {
  const userId = parseInt(req.params.userId);
  const { title, content } = req.body;
  
  // Check if user exists
  const userExists = users.some(user => user.id === userId);
  
  if (!userExists) {
    return res.status(404).json({ message: 'User not found' });
  }
  
  if (!title || !content) {
    return res.status(400).json({ message: 'Title and content are required' });
  }
  
  const newPost = {
    id: posts.length + 1,
    userId,
    title,
    content,
    createdAt: new Date().toISOString()
  };
  
  posts.push(newPost);
  res.status(201).json(newPost);
});
                

Response Formatting and Status Codes

Consistent response formatting and appropriate status codes are essential for creating user-friendly APIs:

Common HTTP Status Codes

• 2XX - Success
  • 200: OK (successful GET, PUT, PATCH)
  • 201: Created (successful POST)
  • 204: No Content (successful DELETE)
• 4XX - Client Errors
  • 400: Bad Request (invalid data)
  • 401: Unauthorized (not authenticated)
  • 403: Forbidden (not authorized)
  • 404: Not Found (resource doesn't exist)
  • 409: Conflict (resource state conflict)
  • 422: Unprocessable Entity (validation errors)
• 5XX - Server Errors
  • 500: Internal Server Error
  • 503: Service Unavailable

// Utility for consistent success responses
const sendSuccessResponse = (res, statusCode, data, meta = {}) => {
  return res.status(statusCode).json({
    success: true,
    data,
    meta
  });
};

// Utility for consistent error responses
const sendErrorResponse = (res, statusCode, message, errors = null) => {
  const response = {
    success: false,
    error: {
      message
    }
  };
  
  if (errors) {
    response.error.details = errors;
  }
  
  return res.status(statusCode).json(response);
};

// Example usage in routes
app.get('/api/users', (req, res) => {
  try {
    // Add pagination
    const page = parseInt(req.query.page) || 1;
    const limit = parseInt(req.query.limit) || 10;
    const startIndex = (page - 1) * limit;
    const endIndex = page * limit;
    
    const paginatedUsers = users.slice(startIndex, endIndex);
    
    // Meta information for pagination
    const meta = {
      total: users.length,
      page,
      limit,
      pages: Math.ceil(users.length / limit)
    };
    
    // Add links for pagination if needed
    if (page < meta.pages) {
      meta.next = `/api/users?page=${page + 1}&limit=${limit}`;
    }
    
    if (page > 1) {
      meta.prev = `/api/users?page=${page - 1}&limit=${limit}`;
    }
    
    return sendSuccessResponse(res, 200, paginatedUsers, meta);
  } catch (error) {
    return sendErrorResponse(res, 500, 'Server error', error.message);
  }
});

app.post('/api/users', (req, res) => {
  const { name, email } = req.body;
  
  // Basic validation
  const errors = [];
  if (!name) errors.push({ field: 'name', message: 'Name is required' });
  if (!email) errors.push({ field: 'email', message: 'Email is required' });
  
  if (errors.length > 0) {
    return sendErrorResponse(res, 400, 'Validation failed', errors);
  }
  
  try {
    const newUser = {
      id: users.length + 1,
      name,
      email,
      createdAt: new Date().toISOString()
    };
    
    users.push(newUser);
    return sendSuccessResponse(res, 201, newUser);
  } catch (error) {
    return sendErrorResponse(res, 500, 'Server error', error.message);
  }
});
                

// GET /repos/octocat/hello-world/issues
{
  "total_count": 1,
  "items": [
    {
      "id": 1,
      "number": 1347,
      "title": "Found a bug",
      "state": "open",
      "user": {
        "login": "octocat",
        "id": 1
      },
      "created_at": "2011-04-22T13:33:48Z",
      "updated_at": "2011-04-22T13:33:48Z"
    }
  ]
}
                

{
  "error": {
    "code": "resource_missing",
    "doc_url": "https://stripe.com/docs/error-codes/resource-missing",
    "message": "No such customer: 'cus_nonexistent'",
    "param": "id",
    "type": "invalid_request_error"
  }
}
                

Implementing Pagination and Filtering

As your API resources grow, pagination and filtering become essential for performance and usability:

// GET /api/products with pagination and filtering
app.get('/api/products', (req, res) => {
  try {
    let filteredProducts = [...products]; // Clone the array
    
    // Apply filters if provided
    if (req.query.category) {
      filteredProducts = filteredProducts.filter(p => 
        p.category === req.query.category
      );
    }
    
    if (req.query.minPrice) {
      const minPrice = parseFloat(req.query.minPrice);
      filteredProducts = filteredProducts.filter(p => p.price >= minPrice);
    }
    
    if (req.query.maxPrice) {
      const maxPrice = parseFloat(req.query.maxPrice);
      filteredProducts = filteredProducts.filter(p => p.price <= maxPrice);
    }
    
    // Search by name
    if (req.query.search) {
      const searchTerm = req.query.search.toLowerCase();
      filteredProducts = filteredProducts.filter(p => 
        p.name.toLowerCase().includes(searchTerm)
      );
    }
    
    // Apply sorting
    if (req.query.sort) {
      const sortField = req.query.sort;
      const sortOrder = req.query.order === 'desc' ? -1 : 1;
      
      filteredProducts.sort((a, b) => {
        if (a[sortField] < b[sortField]) return -1 * sortOrder;
        if (a[sortField] > b[sortField]) return 1 * sortOrder;
        return 0;
      });
    }
    
    // Pagination
    const page = parseInt(req.query.page) || 1;
    const limit = parseInt(req.query.limit) || 10;
    const startIndex = (page - 1) * limit;
    const endIndex = page * limit;
    
    // Count total items before pagination
    const totalItems = filteredProducts.length;
    
    // Apply pagination
    const paginatedProducts = filteredProducts.slice(startIndex, endIndex);
    
    // Create response with pagination metadata
    const response = {
      data: paginatedProducts,
      meta: {
        total: totalItems,
        page,
        limit,
        pages: Math.ceil(totalItems / limit)
      }
    };
    
    // Add links for navigation
    if (page < response.meta.pages) {
      response.meta.next = `${req.path}?page=${page + 1}&limit=${limit}`;
    }
    
    if (page > 1) {
      response.meta.prev = `${req.path}?page=${page - 1}&limit=${limit}`;
    }
    
    res.status(200).json(response);
  } catch (error) {
    res.status(500).json({ 
      success: false,
      error: {
        message: 'Server error',
        details: error.message
      }
    });
  }
});
                

API Versioning Strategies

API versioning is crucial for evolving your API without breaking existing client applications:

Common Versioning Approaches

• URL Path Versioning: /api/v1/users
• Query Parameter Versioning: /api/users?version=1
• Header-based Versioning: Accept: application/vnd.company.v1+json
• Content Negotiation: Accept: application/json; version=1.0

// Create separate routers for each version
const express = require('express');
const app = express();

// Import version-specific routers
const v1UserRouter = require('./routes/v1/users');
const v2UserRouter = require('./routes/v2/users');

// Apply version prefixes
app.use('/api/v1/users', v1UserRouter);
app.use('/api/v2/users', v2UserRouter);

// Example v1 router (routes/v1/users.js)
const v1Router = express.Router();

v1Router.get('/', (req, res) => {
  // Old version returns minimal user data
  const basicUserData = users.map(u => ({
    id: u.id,
    name: u.name,
    email: u.email
  }));
  
  res.status(200).json(basicUserData);
});

// Example v2 router (routes/v2/users.js)
const v2Router = express.Router();

v2Router.get('/', (req, res) => {
  // New version returns enhanced user data
  const enhancedUserData = users.map(u => ({
    id: u.id,
    name: u.name,
    email: u.email,
    role: u.role,
    createdAt: u.createdAt,
    lastLogin: u.lastLogin,
    settings: u.settings
  }));
  
  res.status(200).json({
    data: enhancedUserData,
    meta: {
      total: enhancedUserData.length,
      version: 'v2'
    }
  });
});
                

Documentation and OpenAPI/Swagger

Good documentation is critical for API adoption. OpenAPI (formerly Swagger) provides a standard format for API documentation:

// Install required packages
// npm install swagger-jsdoc swagger-ui-express

const express = require('express');
const swaggerJsdoc = require('swagger-jsdoc');
const swaggerUi = require('swagger-ui-express');

const app = express();
app.use(express.json());

// Swagger definition
const swaggerOptions = {
  definition: {
    openapi: '3.0.0',
    info: {
      title: 'User API',
      version: '1.0.0',
      description: 'A simple Express API for user management'
    },
    servers: [
      {
        url: 'http://localhost:3000'
      }
    ]
  },
  apis: ['./routes/*.js']  // Path to the API routes files
};

const swaggerSpec = swaggerJsdoc(swaggerOptions);
app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerSpec));

// Example of annotated route for Swagger
/**
 * @swagger
 * /api/users:
 *   get:
 *     summary: Returns a list of users
 *     description: Retrieve a list of all users from the database
 *     parameters:
 *       - in: query
 *         name: page
 *         schema:
 *           type: integer
 *           default: 1
 *         description: Page number for pagination
 *       - in: query
 *         name: limit
 *         schema:
 *           type: integer
 *           default: 10
 *         description: Number of items per page
 *     responses:
 *       200:
 *         description: A list of users
 *         content:
 *           application/json:
 *             schema:
 *               type: object
 *               properties:
 *                 data:
 *                   type: array
 *                   items:
 *                     type: object
 *                     properties:
 *                       id:
 *                         type: integer
 *                       name:
 *                         type: string
 *                       email:
 *                         type: string
 *                 meta:
 *                   type: object
 *                   properties:
 *                     total:
 *                       type: integer
 *                     page:
 *                       type: integer
 *                     limit:
 *                       type: integer
 *                     pages:
 *                       type: integer
 */
app.get('/api/users', (req, res) => {
  // Implementation as before...
});

/**
 * @swagger
 * /api/users/{id}:
 *   get:
 *     summary: Get a user by ID
 *     parameters:
 *       - in: path
 *         name: id
 *         required: true
 *         schema:
 *           type: integer
 *         description: User ID
 *     responses:
 *       200:
 *         description: User details
 *       404:
 *         description: User not found
 */
app.get('/api/users/:id', (req, res) => {
  // Implementation as before...
});

// Start the server
app.listen(3000, () => {
  console.log('API documentation available at http://localhost:3000/api-docs');
});
                

Practical Exercise: Building a RESTful API

Let's create a complete e-commerce API with Express. This exercise will help you practice RESTful principles in a real-world scenario.

e-commerce-api/
├── package.json
├── server.js
├── routes/
│   ├── products.js
│   ├── categories.js
│   └── orders.js
├── controllers/
│   ├── productController.js
│   ├── categoryController.js
│   └── orderController.js
├── models/  // In-memory data for this exercise
│   ├── Product.js
│   ├── Category.js
│   └── Order.js
├── middleware/
│   └── validation.js
└── util/
    └── apiResponse.js
                

Further Resources

• Express Routing Guide
• RESTful API Design Guidelines
• OpenAPI Specification
• Microsoft REST API Guidelines
• JSON:API Specification
• Stripe API Documentation (Good Example)