# AGENTS.md: REST API design rules

## Resources and methods
- Plural nouns, kebab-case paths: `/v1/order-items/{id}`. Nest at most one level (`/users/{id}/orders`).
- `GET` read (safe), `POST` create or action, `PUT` full replace, `PATCH` partial update, `DELETE` remove. Actions that don't fit use a sub-resource (`POST /orders/{id}/cancel`).
- JSON fields in one casing across the API (match the existing API; default `camelCase`). Timestamps ISO 8601 in UTC; money as integer minor units + currency.

## Status codes
- `200` OK, `201` Created (with `Location`), `204` No Content, `400` malformed, `401` unauthenticated, `403` forbidden, `404` not found, `409` conflict, `422` validation failed, `429` rate limited (with `Retry-After`), `5xx` server faults only.

## Errors
- One shape everywhere, RFC 9457 Problem Details: `{ "type", "title", "status", "detail", "errors": [{ "field", "message" }] }`. Never return stack traces.

## Lists
- Paginate every list: cursor-based (`?limit=50&cursor=...` returning `nextCursor`). Cap `limit`.
- Filtering and sorting via query params (`?status=paid&sort=-createdAt`).

## Safety and evolution
- `POST` endpoints that create payments or orders accept an `Idempotency-Key` header.
- Additive changes only within a version: new optional fields are fine; removing/renaming fields or changing types needs a new version or deprecation period (`Deprecation`/`Sunset` headers).
- Update the OpenAPI spec (`openapi.yaml`) in the same change and keep it valid (`npx @redocly/cli lint`).