sagargupta16/api-design

API Design Patterns

Quick Reference

| Task | Approach | |------|----------| | URL structure | Nouns for resources, HTTP verbs for actions | | Versioning | URL prefix (/api/v1/) for most projects | | Errors | RFC 9457 problem details format | | Pagination | Cursor-based for large datasets, offset for small | | Auth | JWT bearer tokens or API keys depending on use case | | Docs | OpenAPI 3.1 spec, auto-generated where possible |

URL Structure

Resource Naming

GET    /api/v1/users           # List users
POST   /api/v1/users           # Create user
GET    /api/v1/users/{id}      # Get user by ID
PUT    /api/v1/users/{id}      # Replace user
PATCH  /api/v1/users/{id}      # Partial update
DELETE /api/v1/users/{id}      # Delete user

GET    /api/v1/users/{id}/orders    # Nested resource
POST   /api/v1/users/{id}/orders    # Create nested resource

Rules:

• Plural nouns for collections: /users not /user
• Kebab-case for multi-word resources: /order-items
• No verbs in URLs: /users/{id}/activate not /activateUser
• Max 2 levels of nesting, then use query params or top-level resources

Filtering, Sorting, Search

GET /api/v1/users?status=active&role=admin       # Filter
GET /api/v1/users?sort=-created_at,name           # Sort (- for desc)
GET /api/v1/users?search=john                     # Search
GET /api/v1/users?fields=id,name,email            # Sparse fields

HTTP Methods and Status Codes

Methods

| Method | Purpose | Idempotent | Body | |--------|---------|-----------|------| | GET | Read resource(s) | Yes | No | | POST | Create resource | No | Yes | | PUT | Replace resource | Yes | Yes | | PATCH | Partial update | No | Yes | | DELETE | Remove resource | Yes | No |

Status Codes

| Code | When to Use | |------|-------------| | 200 | Successful GET, PUT, PATCH, DELETE | | 201 | Successful POST (resource created) | | 204 | Successful DELETE with no body | | 400 | Invalid request body or params | | 401 | Missing or invalid authentication | | 403 | Authenticated but not authorized | | 404 | Resource not found | | 409 | Conflict (duplicate, state violation) | | 422 | Valid JSON but failed validation | | 429 | Rate limit exceeded | | 500 | Unhandled server error |

Error Response Format

Use RFC 9457 Problem Details:

{
  "type": "https://api.example.com/errors/validation",
  "title": "Validation Error",
  "status": 422,
  "detail": "Email address is already in use",
  "instance": "/api/v1/users",
  "errors": [
    {
      "field": "email",
      "message": "Email '[email protected]' is already registered"
    }
  ]
}

Rules:

• Always include status, title, and detail
• Use errors array for field-level validation failures
• Never expose stack traces or internal details in production
• Use consistent error types across the API

Framework Implementation

FastAPI:

from fastapi import HTTPException
from fastapi.responses import JSONResponse

@app.exception_handler(HTTPException)
async def http_exception_handler(request, exc):
    return JSONResponse(
        status_code=exc.status_code,
        content={
            "type": f"https://api.example.com/errors/{exc.status_code}",
            "title": exc.detail,
            "status": exc.status_code,
        },
    )

Express:

app.use((err, req, res, next) => {
  const status = err.status || 500;
  res.status(status).json({
    type: `https://api.example.com/errors/${status}`,
    title: err.message,
    status,
  });
});

Versioning

| Strategy | Format | When to Use | |----------|--------|-------------| | URL prefix | /api/v1/users | Default choice -- simple, visible, cacheable | | Header | Accept: application/vnd.api+json;version=2 | When URL stability matters | | Query param | /api/users?version=2 | Avoid -- poor caching |

When to bump versions:

• Removing a field from a response: breaking (bump major)
• Adding an optional field: non-breaking (no bump)
• Changing a field type: breaking (bump major)
• Adding a new endpoint: non-breaking (no bump)

Pagination

Cursor-Based (recommended for large datasets)

{
  "data": [...],
  "pagination": {
    "next_cursor": "eyJpZCI6MTAwfQ==",
    "has_more": true
  }
}

Request: GET /api/v1/users?cursor=eyJpZCI6MTAwfQ==&limit=25

Advantages: consistent results, no skipped/duplicated items on insert/delete.

Offset-Based (simpler, for small datasets)

{
  "data": [...],
  "pagination": {
    "total": 150,
    "page": 2,
    "per_page": 25,
    "total_pages": 6
  }
}

Request: GET /api/v1/users?page=2&per_page=25

Default Limits

Always enforce a max page size server-side:

@router.get("/users")
async def list_users(page: int = 1, per_page: int = Query(default=25, le=100)):
    ...

Authentication Patterns

| Pattern | Use Case | Implementation | |---------|----------|---------------| | JWT Bearer | SPA, mobile apps | Authorization: Bearer <token> | | API Key | Server-to-server, third-party integrations | X-API-Key: <key> or query param | | Session cookie | Traditional web apps | Set-Cookie: session=<id> | | OAuth 2.0 | Third-party login | Authorization code flow |

JWT structure:

Header: {"alg": "HS256", "typ": "JWT"}
Payload: {"sub": "user_123", "exp": 1700000000, "role": "admin"}

Rules:

• Short token expiry (15min access, 7d refresh)
• Store refresh tokens server-side
• Never store JWTs in localStorage (use httpOnly cookies)
• Validate tokens on every request

Rate Limiting

Response headers:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1700000060
Retry-After: 30

Common limits:

• Public APIs: 60-100 requests/minute
• Authenticated: 1000 requests/minute
• Write operations: Lower limits than reads

Return 429 Too Many Requests with Retry-After header.

OpenAPI / Swagger

Auto-generate where possible:

• FastAPI: Built-in at /docs (Swagger UI) and /redoc
• Express: Use swagger-jsdoc + swagger-ui-express
• Go: Use swag annotations
• NestJS: @nestjs/swagger decorators

Minimum spec:

openapi: "3.1.0"
info:
  title: API Name
  version: "1.0.0"
paths:
  /api/v1/users:
    get:
      summary: List users
      parameters:
        - name: page
          in: query
          schema: { type: integer, default: 1 }
      responses:
        "200":
          description: User list

Anti-Patterns

| Don't | Do Instead | |-------|-----------| | Use verbs in URLs (/getUsers) | Use HTTP methods on noun resources | | Return 200 for errors with error body | Use proper HTTP status codes | | Expose database IDs directly | Use UUIDs or opaque IDs | | Return different error formats per endpoint | Use consistent error schema everywhere | | Paginate without a max limit | Always enforce server-side max page size | | Version every minor change | Only version on breaking changes | | Return full nested objects always | Support sparse fields or use separate endpoints | | Accept * CORS in production | Whitelist specific origins from env vars |