api-design

Use plural, lowercase, kebab-case nouns for resources like /api/v1/team-members, and nest sub-resources for ownership such as /api/v1/users/:id/orders. Avoid verbs in URLs except for non-CRUD actions like /api/v1/auth/login.

Use offset pagination for admin dashboards and small datasets under 10K rows where users jump to page numbers. Use cursor pagination for infinite scroll, feeds, and large datasets since it performs consistently and stays stable with concurrent inserts.

Return 201 Created with a Location header pointing to the new resource, such as Location: /api/v1/users/abc-123. Avoid returning 200 for created resources, and use 204 No Content for DELETE or updates without a response body.

Return an error object with a machine-readable code, a human-readable message, and a details array of field-level errors for validation failures. Pair it with the correct HTTP status like 400 for malformed JSON or 422 for semantically invalid data.

Version only for breaking changes like removing fields, changing types, or altering authentication. URL path versioning like /api/v2/ is recommended because it is explicit and cacheable; maintain at most two active versions with a Sunset header for deprecation.

Return X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset on responses. When the limit is exceeded, return 429 Too Many Requests with a Retry-After header and an error body explaining when to retry.