REST API Design

URL Structure

• /api/v1/resources — versioned, plural nouns
• /api/v1/resources/123 — single resource by ID
• /api/v1/resources/123/relationships — sub-resources
• Query params for filtering, sorting, pagination: ?status=active&sort=-created_at&page=2&per_page=20

HTTP Methods & Status Codes

Response Format

{
  "data": { ... },
  "meta": { "page": 1, "per_page": 20, "total": 100 },
  "error": null
}

Error Format

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid email address",
    "details": [
      { "field": "email", "message": "must be a valid email", "code": "invalid_format" }
    ]
  }
}

Pagination

• Use cursor-based pagination for large datasets (stable under writes)
• Use offset-based for simpler cases (small datasets, admin UIs)
• Return next_cursor or next_page in response meta
• Default page size, enforce max page size