api-design

Use plural kebab-case resource URLs and match status codes to outcomes: 200 for reads, 201 with a Location header for creation, 204 for deletes, 400 for malformed requests, 422 for validation failures, and 409 for state conflicts. Never return 200 with a success flag in the body.

400 means the request could not be parsed, such as malformed JSON or a missing required parameter. 422 means the request parsed successfully but the values failed semantic validation. If you only use one, pick 400 and stay consistent because clients branch on it.

Use cursor pagination for feeds, large or actively-written tables, and public APIs, since offset skips and duplicates rows when items are inserted mid-pagination. Offset is acceptable for admin tables under roughly 10k rows where users expect page numbers. Always cap the limit server-side.

A new version is needed for breaking changes: removing or renaming a field, narrowing a type, changing a status code or error code for an existing condition, or making an optional parameter required. Adding fields, optional parameters, or endpoints is not breaking and needs no new version.

QUERY (RFC 10008) is a safe, idempotent, cacheable method for reads whose parameters are too structured for a URL, like nested boolean filters. Browser fetch cannot send it yet, so accept QUERY alongside POST on the same endpoint rather than requiring it.

It covers only the wire contract: URLs, methods, status codes, and response shapes. It does not address handler internals, persistence, caching, or background work, and it does not cover GraphQL, gRPC, or security vulnerability review.