AGENTS.md — REST API design

Design resources, status codes, errors and pagination deliberately and write them down first, so clients can integrate once and keep working as the API evolves.

How to do it

1. Model the resources — Name the nouns the client works with (orders, line-items, refunds) as plural collection paths with stable ids: /orders, /orders/{orderId}. Nest only for true ownership and no deeper than one level. Express actions that do not fit CRUD as sub-resources (POST /orders/{id}/cancellation).
2. Write the contract first — Describe the endpoints in an OpenAPI document before implementing: methods, request and response schemas, required fields, examples, error responses and auth. Review the contract with a consumer before writing handlers.
3. Use methods and status codes precisely — GET reads and is safe; PUT replaces and is idempotent; PATCH partially updates; DELETE removes and is idempotent; POST creates or triggers. Return 200 with a body, 201 with a Location header on create, 204 with no body, 400 for malformed input, 401 unauthenticated, 403 forbidden, 404 not found, 409 conflict, 422 validation failure, 429 rate limited.
4. Return one error shape everywhere — Use a single machine-readable error format, such as application/problem+json with type, title, status, detail and a field-level errors array. Include a stable error code clients can branch on and a request id for support.
5. Paginate every list — Never return an unbounded collection. Use cursor pagination for large or changing data (limit plus an opaque next cursor), set a default and maximum page size, and document the sort order.
6. Make writes safe to retry — Accept an Idempotency-Key header on POST endpoints that create or charge. Store the key with the response for a fixed window and replay the original response on repeat; return 409 if the same key arrives with a different body. Use ETags with If-Match for optimistic concurrency on updates.
7. Plan for change without breaking clients — Adding optional fields and new endpoints is non-breaking. Removing or renaming fields, tightening validation or changing meaning is breaking: ship it under a new major version (path /v2 or a version header), run both, announce a deprecation date with Deprecation and Sunset headers, and remove only after usage drops.
8. Test the contract — Validate real responses against the OpenAPI schema in CI and run a breaking-change diff between the main branch contract and the pull request.

Checklist (before a pull request)

• An OpenAPI document describes every changed endpoint with examples
• Paths are plural nouns with stable ids and at most one level of nesting
• Each endpoint returns the documented status codes and one error shape
• Every list endpoint is paginated with a maximum page size
• Create and charge endpoints accept an idempotency key
• The breaking-change check passes or a new major version is introduced
• Responses are validated against the schema in tests

Rules

• Use one naming convention for fields across the API (for example camelCase) and ISO 8601 UTC timestamps. (Mixed conventions force every client to special-case fields.)
• Never return 200 with an error in the body; the status code must reflect the outcome. (Clients, proxies and monitoring all rely on status codes.)
• Authorise every request against the resource being accessed and return 404 rather than 403 when revealing existence would leak data. (Sequential or guessable ids invite enumeration.)
• Cap page sizes and support conditional GET with ETags. (Unbounded lists and repeated full downloads overload both server and client.)
• Never remove or change the meaning of a field within a major version. (Clients you cannot see will break silently.)

Checks

Generated from the Celestial engineering practice “REST API design”.