api-design-patterns

Use plural nouns like /users and /orders, nest relationships up to two levels deep, and apply kebab-case for multi-word resources. Never put verbs in URLs; model actions as resources instead, such as POST /users/{id}/activation.

Use cursor pagination for large or frequently changing datasets, encoding cursors as opaque base64 strings without exposing raw IDs. Use offset pagination only when the dataset is small and total count is cheap to compute.

Return 200 for reads and updates, 201 with a Location header for creation, 204 for deletes, 400 for validation errors, 401/403 for auth issues, 404 for missing resources, 409 for conflicts, 422 for semantic errors, and 429 with Retry-After for rate limits.

Use URL path versioning like /api/v1/users and never remove fields from a published version. Introduce new required fields only in a new version, deprecate old versions with a Sunset header and six-month notice, and support at most two active versions.

Return a consistent JSON envelope with an error object containing a code, message, and details array of field-level errors. Use stable error codes across the API and document every code in the API reference.

Apply per-user, per-endpoint limits using a sliding window algorithm. Return 429 with a Retry-After header, include X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers, and exempt health check and auth endpoints.