dragonked2 / api-design

API Design Skill

Design clean, consistent, and maintainable APIs.

RESTful Design Principles

• Use nouns for resources, HTTP verbs for actions
• Consistent URL patterns: /resources/{id}/sub-resources
• Proper HTTP status codes (200, 201, 204, 400, 401, 403, 404, 409, 422, 500)
• Stateless: each request contains all needed info
• HATEOAS: include links for discoverability

API Response Schema

{
  "data": {},
  "meta": { "page": 1, "per_page": 20, "total": 100 },
  "links": { "self": "...", "next": "...", "prev": "..." },
  "errors": []
}

Error Schema

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Human-readable description",
    "details": [{"field": "email", "issue": "invalid format"}]
  }
}

Key Patterns

• Pagination: cursor-based for large datasets, offset for small
• Filtering: query params ?status=active&created_after=2024-01-01
• Sorting: ?sort=-created_at,name
• Rate Limiting: 429 + Retry-After header
• Versioning: URL path (/v2/) or header
• Idempotency: idempotency keys for safe retries