REST API Design Patterns

REST API Design Patterns

A comprehensive skill for designing, implementing, and maintaining RESTful APIs. Master resource modeling, HTTP methods, versioning strategies, pagination, filtering, error handling, and best practices for building scalable, maintainable APIs using FastAPI, Express.js, and modern frameworks.

When to Use This Skill

Use this skill when:

• Designing a new RESTful API from scratch
• Building microservices with HTTP/REST interfaces
• Refactoring existing APIs for better design and consistency
• Implementing CRUD operations with proper HTTP semantics
• Adding versioning to an existing API
• Designing resource relationships and nested endpoints
• Implementing pagination, filtering, and sorting
• Handling errors and validation consistently
• Building hypermedia-driven APIs (HATEOAS)
• Optimizing API performance with caching and compression
• Documenting APIs with OpenAPI/Swagger specifications
• Ensuring API security with authentication and authorization patterns

Core REST Principles

What is REST?

REST (Representational State Transfer) is an architectural style for distributed systems that emphasizes:

1. Resource-Based: Everything is a resource with a unique identifier (URI)
2. Standard Methods: Use standard HTTP methods (GET, POST, PUT, DELETE, PATCH)
3. Stateless: Each request contains all information needed to process it
4. Client-Server: Clear separation between client and server
5. Cacheable: Responses can be cached for performance
6. Uniform Interface: Consistent patterns across the API

REST Maturity Model (Richardson Maturity Model)

Level 0 - The Swamp of POX: Single URI, single HTTP method (usually POST)

• Example: /api with all operations in POST body

Level 1 - Resources: Multiple URIs, each representing a resource

• Example: /users, /posts, /products

Level 2 - HTTP Verbs: Proper use of HTTP methods

• Example: GET /users/123, POST /users, PUT /users/123

Level 3 - Hypermedia Controls (HATEOAS): API responses include links to related resources

• Example: Response includes "_links": {"self": "/users/123", "posts": "/users/123/posts"}

Resource Modeling

Resource Naming Conventions

1. Use Nouns, Not Verbs

Good:
  GET /users
  GET /products
  POST /orders

Bad:
  GET /getUsers
  GET /getAllProducts
  POST /createOrder

2. Use Plural Nouns for Collections

Good:
  GET /users          # Collection
  GET /users/123      # Individual resource

Bad:
  GET /user
  GET /user/123

3. Use Lowercase and Hyphens

Good:
  /user-profiles
  /order-items
  /payment-methods

Bad:
  /userProfiles
  /OrderItems
  /payment_methods

4. Hierarchy for Related Resources

Good:
  /users/123/posts
  /users/123/posts/456
  /users/123/posts/456/comments

Avoid Deep Nesting (max 2-3 levels):
  /organizations/1/departments/2/teams/3/members/4/tasks/5  # Too deep!

Resource Design Patterns

Pattern 1: Collection and Item Resources

Collection Resource:
  GET    /products          # List all products
  POST   /products          # Create new product

Item Resource:
  GET    /products/123      # Get specific product
  PUT    /products/123      # Replace product (full update)
  PATCH  /products/123      # Partial update
  DELETE /products/123      # Delete product

Pattern 2: Nested Resources (Parent-Child Relationships)

# Comments belong to posts
GET    /posts/42/comments       # List comments for post 42
POST   /posts/42/comments       # Create comment on post 42
GET    /posts/42/comments/7     # Get specific comment
DELETE /posts/42/comments/7     # Delete specific comment

# Alternative for accessing comments directly
GET    /comments/7              # Get comment by ID (if you have it)

Pattern 3: Filtering Collections (Query Parameters)

GET /products?category=electronics
GET /products?price_min=100&price_max=500
GET /products?sort=price&order=desc
GET /users?status=active&role=admin
GET /posts?author=123&published=true

Pattern 4: Actions on Resources (Controllers)

For operations that don't fit standard CRUD:

POST /users/123/activate          # Activate user account
POST /orders/456/cancel           # Cancel order
POST /payments/789/refund         # Refund payment
POST /documents/321/publish       # Publish document
POST /subscriptions/654/renew     # Renew subscription

Pattern 5: Bulk Operations

POST /users/bulk-create           # Create multiple users
PATCH /products/bulk-update       # Update multiple products
DELETE /orders/bulk-delete        # Delete multiple orders

# Or using query parameters
DELETE /orders?ids=1,2,3,4,5

HTTP Methods Deep Dive

GET - Retrieve Resources

Characteristics:

• Safe: No side effects
• Idempotent: Multiple identical requests have the same effect
• Cacheable: Responses can be cached

FastAPI Example:

from fastapi import FastAPI, HTTPException
from typing import List, Optional

app = FastAPI()

# Collection endpoint
@app.get("/items/")
async def list_items(
    skip: int = 0,
    limit: int = 10,
    category: Optional[str] = None
) -> List[dict]:
    """List items with pagination and filtering."""
    # Filter and paginate
    items = get_items_from_db(skip=skip, limit=limit, category=category)
    return items

# Individual resource endpoint
@app.get("/items/{item_id}")
async def get_item(item_id: int) -> dict:
    """Get a specific item by ID."""
    item = get_item_from_db(item_id)
    if not item:
        raise HTTPException(status_code=404, detail="Item not found")
    return item

Express.js Example:

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

// Collection endpoint
app.get('/items', async (req, res) => {
  try {
    const { skip = 0, limit = 10, category } = req.query;
    const items = await getItemsFromDB({ skip, limit, category });
    res.json(items);
  } catch (error) {
    res.status(500).json({ error: 'Internal server error' });
  }
});

// Individual resource endpoint
app.get('/items/:id', async (req, res) => {
  try {
    const item = await getItemFromDB(req.params.id);
    if (!item) {
      return res.status(404).json({ error: 'Item not found' });
    }
    res.json(item);
  } catch (error) {
    res.status(500).json({ error: 'Internal server error' });
  }
});

POST - Create Resources

Characteristics:

• Not safe: Has side effects (creates resource)
• Not idempotent: Multiple requests create multiple resources
• Response should include Location header with new resource URI

FastAPI Example:

from fastapi import FastAPI, HTTPException, status
from pydantic import BaseModel

class ItemCreate(BaseModel):
    name: str
    price: float
    category: str
    description: Optional[str] = None

@app.post("/items/", status_code=status.HTTP_201_CREATED)
async def create_item(item: ItemCreate, response: Response) -> dict:
    """Create a new item."""
    # Validate and create
    new_item = create_item_in_db(item)

    # Set Location header
    response.headers["Location"] = f"/items/{new_item.id}"

    return new_item

Express.js Example:

app.use(express.json());

app.post('/items', async (req, res) => {
  try {
    const { name, price, category, description } = req.body;

    // Validate
    if (!name || !price || !category) {
      return res.status(400).json({
        error: 'Missing required fields: name, price, category'
      });
    }

    // Create resource
    const newItem = await createItemInDB({ name, price, category, description });

    // Set Location header and return 201
    res.location(`/items/${newItem.id}`)
       .status(201)
       .json(newItem);
  } catch (error) {
    res.status(500).json({ error: 'Internal server error' });
  }
});

PUT - Replace Resource

Characteristics:

• Not safe: Has side effects