api-conventions

These conventions apply to every API endpoint in this codebase. Follow them exactly. If a new situation requires deviation, document the reason in a code comment.

URL structure

Pattern: /api/v{major}/{resource}

• Resource names are plural nouns in kebab-case: /api/v1/users, /api/v1/billing-accounts
• Nested resources use path segments: /api/v1/users/{id}/sessions
• Do not use verbs in URLs: use /api/v1/users/{id} with DELETE, not /api/v1/delete-user/{id}
• Query parameters are kebab-case: ?page-size=20&sort-by=created-at

HTTP methods

Method	Meaning	Success status
GET	Retrieve resource(s), no side effects	200
POST	Create a new resource	201
PUT	Replace a resource entirely	200
PATCH	Partially update a resource	200
DELETE	Delete a resource	204 (no body)

Use GET for all read operations. Do not use POST for reads.

Response envelope

All successful responses (except 204) use this envelope:

{
  "data": <resource or array of resources>,
  "meta": {
    "timestamp": "<ISO 8601 UTC>",
    "version": "<API minor version string, e.g. 1.4>"
  }
}

For list responses, meta also includes pagination fields:

{
  "data": [...],
  "meta": {
    "timestamp": "2024-11-01T14:30:00Z",
    "version": "1.4",
    "next_cursor": "<opaque cursor string or null>",
    "limit": 20,
    "count": 20
  }
}

count is the number of items in the current page, not the total across all pages. Do not include a total count unless explicitly required, as it forces an expensive COUNT query.

Error format

All error responses use this envelope:

{
  "error": {
    "code": "SNAKE_CASE_ERROR_CODE",
    "message": "Human-readable description safe for end users.",
    "details": {}
  }
}

• code is a stable machine-readable identifier in SCREAMING_SNAKE_CASE
• message is safe for end users — do not include stack traces, SQL, or internal paths
• details carries structured field-level information for validation errors: