Api Design

HTTP Method Semantics

Nested Resources — Limit to 2 Levels

# Good — 2 levels max
GET /suppliers/:id/invoices
GET /suppliers/:id/invoices/:invoiceId

# Avoid deep nesting — complexity explodes
GET /companies/:id/suppliers/:sid/invoices/:iid/line-items/:lid  # too deep
# Instead:
GET /invoices/:iid/line-items/:lid  # flatten with query params for filtering

Request & Response Standards

Consistent Response Envelope

Success (list)

{
  "data": [...],
  "pagination": {
    "page": 1,
    "pageSize": 20,
    "total": 142,
    "hasNextPage": true
  }
}

Success (single item)

{
  "data": {
    "id": "ord_abc123",
    "status": "confirmed",
    "createdAt": "2024-01-15T10:30:00Z"
  }
}

Error

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "details": [
      { "field": "quantity", "message": "Must be a positive integer" },
      { "field": "price", "message": "Required" }
    ],
    "requestId": "req_xyz789"
  }
}

Error Code System

Define a finite list of machine-readable error codes:

VALIDATION_ERROR      — Client sent invalid data
NOT_FOUND             — Resource doesn't exist
UNAUTHORIZED          — Not authenticated
FORBIDDEN             — Authenticated but not authorized
CONFLICT              — State conflict (duplicate, concurrent edit)
RATE_LIMITED          — Too many requests
INTERNAL_ERROR        — Server-side unexpected error

Pagination

Cursor-Based (preferred for large/live datasets)

GET /transactions?cursor=eyJpZCI6MTAwfQ&limit=20

Response:
{
  "data": [...],
  "pagination": {
    "nextCursor": "eyJpZCI6MTIwfQ",
    "hasNextPage": true
  }
}

Offset-Based (simpler, for small/static datasets)

GET /products?page=2&pageSize=20

Response:
{
  "data": [...],
  "pagination": { "page": 2, "pageSize": 20, "total": 200 }
}

Never return unbounded lists. Always paginate.

Filtering, Sorting, and Field Selection

# Filtering — use query parameters
GET /transactions?status=completed&startDate=2024-01-01&endDate=2024-01-31

# Sorting — field and direction
GET /products?sort=price&order=asc
GET /orders?sort=createdAt&order=desc

# Field selection (reduces payload size)
GET /users?fields=id,name,email

Versioning Strategy

URL Versioning (most explicit, recommended for public APIs)

/api/v1/orders
/api/v2/orders

Header Versioning (cleaner URLs, harder to test manually)

GET /api/orders
Accept-Version: v2

Versioning Rules

• Never break existing clients without a new version
• Deprecate before removing — add Deprecation header
• Support at least 2 major versions simultaneously during transition
• Document what changed between versions

Backwards-Compatible Changes (no version bump needed)

• Adding new optional fields to responses
• Adding new optional query parameters
• Adding new endpoints
• Adding new enum values to existing fields (risky — test consumers)

Breaking Changes (require new version)

• Removing or renaming fields
• Changing field types
• Changing HTTP method or URL
• Changing error code structure

Authentication & Authorization Headers

Bearer Token (JWT)

Authorization: Bearer eyJhbGciOiJIUzI1NiJ9...

API Key

X-API-Key: ak_live_abc123xyz

Core Rules

• HTTPS only on all authenticated endpoints
• Tokens should be short-lived (15–60 min)
• Never pass tokens in URL query parameters (they appear in logs)
• Rate limit authentication endpoints aggressively

Rate Limiting

Response Headers

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 87
X-RateLimit-Reset: 1705312800
Retry-After: 60  (only on 429 response)

Strategy by Endpoint Type

OpenAPI Documentation

Every API must have an OpenAPI 3.x spec. Generate from code annotations or maintain as source of truth: