rest-api-design-patterns

What this skill does

# 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:**

```python
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:**

```javascript
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:**

```python
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:**

```javascript
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
- Idempotent: Multiple identical requests have