api-design

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

Return 200 for successful reads, 201 with a Location header for creations, and 204 for deletions. Use 400 or 422 for validation failures, 401/403 for auth issues, 404 for missing resources, 409 for conflicts, and 429 for rate limiting instead of returning 200 for everything.

Use offset pagination for admin dashboards, small datasets, and search results where users expect page numbers. Use cursor pagination for infinite scroll, feeds, and large datasets because it performs consistently regardless of position and stays stable with concurrent inserts.

Start with URL path versioning like /api/v1/ and maintain at most two active versions. Non-breaking changes such as adding fields or optional parameters need no new version; removing fields or changing types does. Announce deprecations with a Sunset header and return 410 Gone after the sunset date.

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