api-design

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

Return 200 for successful reads, 201 with a Location header for creations, 204 for deletions, 400 or 422 for validation failures, 404 for missing resources, 409 for conflicts, and 429 for rate limiting. Never return 200 for errors.

Use cursor pagination for large datasets, infinite scroll, and public APIs since it performs consistently and stays stable with concurrent inserts. Use offset pagination for admin dashboards, small datasets, and search results where users expect page numbers.

Start with URL path versioning like /api/v1/ and maintain at most two active versions. Non-breaking changes such as adding fields or endpoints need no new version, while removing fields or changing types requires one, with a Sunset header before retirement.

Return an error object with a machine-readable code, a human-readable message, and a details array containing field-level validation errors with field name, message, and code. Pair this with the correct HTTP status code such as 422 for semantic validation failures.