API Standards

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.