rest-api-design

Use plural nouns for resources like /api/users instead of verbs like /api/getUsers, and map CRUD operations to HTTP methods: GET for reads, POST for creation, PUT/PATCH for updates, and DELETE for removal. Limit nesting to two levels, such as /api/users/123/orders.

Return 200 for successful reads, 201 for resource creation, 204 for deletions without a body, 400 for invalid requests, 401/403 for auth failures, 404 for missing resources, 409 for conflicts like duplicate emails, 422 for validation errors, and 429 for rate limiting.

Accept page and limit query parameters, then return a pagination object with page, limit, total, totalPages, hasNext, and hasPrev alongside the data array. Optionally include HATEOAS-style links for self, first, prev, next, and last pages.

URL path versioning such as /api/v1/users is the recommended approach because it is explicit and easy to route. Header-based versioning via Accept: application/vnd.myapi.v1+json is an alternative, while query parameter versioning is not recommended.

Return a structured error object containing a machine-readable code, a human-readable message, and a details array with field-level validation messages. Include metadata like timestamp and requestId to support debugging and client-side error handling.