Home › API design › REST API design AGENTS.md

REST API design AGENTS.md

AGENTS.md for designing consistent HTTP/JSON APIs: resource naming, status codes, errors, pagination, and versioning.

AGENTS.mdAPI design

How to use

Save this as AGENTS.md in your repository root, commit it, and your agent will pick it up automatically. Edit the commands to match your project.

# 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`).