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

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:

{
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "One or more fields failed validation.",
    "details": {
      "fields": [
        { "field": "email", "message": "Must be a valid email address." },
        { "field": "birth_date", "message": "Must be in the past." }
      ]
    }
  }
}

Status codes

Do not use 400 for validation errors — use 422. Do not use 500 for expected error cases that have a more specific code.

Authentication

All protected endpoints require a Bearer token in the Authorization header:

Authorization: Bearer <token>

The token is validated by the auth middleware before the handler runs. Handlers do not validate tokens directly. If the middleware passes, request.user (or the framework equivalent) is populated with the authenticated user's identity.

Pagination

Use cursor-based pagination, not offset-based.

Request parameters:

• cursor: opaque cursor string from the previous page's next_cursor (absent on first page)
• limit: number of items to return, default 20, maximum 100

Response meta fields:

• next_cursor: cursor to pass for the next page, or null if this is the last page
• limit: the limit used for this page
• count: number of items returned in this page

Do not expose integer offsets or page numbers in the public API.

Versioning

• Major version in the URL path: /api/v1/, /api/v2/
• Minor version in the response header: X-API-Version: 1.4
• Breaking changes require a new major version
• Additive changes (new fields, new endpoints) increment the minor version
• Deprecated fields are kept for at least two minor versions before removal