api-lifecycle

API Lifecycle

API Design Principles

• Resource-oriented design: Model APIs around resources (nouns), not actions (verbs). Use GET /orders/123 not GET /getOrder?id=123. Nest sub-resources logically: GET /users/123/orders. Keep nesting to a maximum of two levels.
• Idempotency: GET, PUT, and DELETE must be idempotent. Repeated calls produce the same result. For POST (create) operations, support client-provided idempotency keys (Idempotency-Key header) to prevent duplicate resource creation on retries.
• Stateless requests: Every request must contain all information needed to process it. Do not store client session state on the server between requests. Use tokens (JWT, opaque) for authentication context.
• Pagination: Always paginate list endpoints. Choose the appropriate strategy:
  • Cursor-based (recommended): Use an opaque cursor token. Best for real-time data, large datasets, and when items can be inserted/deleted between pages. Return next_cursor in the response.
  • Offset-based: Use ?offset=20&limit=10. Simpler to implement but has consistency issues with changing datasets. Acceptable for admin UIs and static data.
  • Always include total_count (or indicate if more pages exist), next link, and the current page size in the response.
• Consistent naming: Use snake_case for JSON fields (created_at, not createdAt). Use plural nouns for collection endpoints (/users, not /user). Use kebab-case for URL paths (/order-items, not /orderItems). Be consistent across the entire API.
• HTTP methods and status codes: Use methods correctly: GET (read), POST (create), PUT (full replace), PATCH (partial update), DELETE (remove). Return appropriate status codes: 200 (success), 201 (created), 204 (no content), 400 (bad request), 401 (unauthorized), 403 (forbidden), 404 (not found), 409 (conflict), 422 (unprocessable entity), 429 (rate limited), 500 (server error).

Versioning Strategies