| name | api-standards |
| description | Atlas REST/HTTP API design conventions for AI coding agents. Use when designing, implementing, or changing an HTTP endpoint, request/response schema, or error format in an Atlas service. Covers resource naming, versioning, status codes, pagination, and error envelopes. Don't use for gRPC/event schemas or for non-Atlas services. |
| license | MIT |
| metadata | {"author":"Atlas Platform Engineering","version":"1.0"} |
Atlas API Design Standards
Consistency is the feature. New and changed HTTP APIs follow these conventions.
Resources and naming
- Nouns, plural, lowercase, kebab-case:
/purchase-orders, /purchase-orders/{id}/line-items.
- Use HTTP methods for verbs (GET, POST, PATCH, DELETE). No verbs in paths.
Versioning and compatibility
- Version in the path:
/v1/.... Additive changes only within a version.
- Never repurpose or remove a field in a released version; add a new one and deprecate the old.
Status codes
200/201/204 for success, 400 invalid input, 401/403 auth, 404 missing, 409 conflict, 422 semantic validation, 429 rate limit, 5xx server.
Pagination and filtering
- Cursor-based pagination:
?limit= + ?cursor=, return next_cursor. Do not expose raw offsets.
- Filtering and sorting via explicit query params; never accept arbitrary query expressions.
Error envelope
Return a consistent JSON error body:
{ "error": { "code": "invalid_argument", "message": "human-readable", "details": [] } }
code is a stable machine string; message is for humans; never leak stack traces or SQL.
