API Conventions

This page records response-shape conventions for new RESTful API endpoints.

Versioning

New RESTful endpoints should use /api/v2 and should not add /api/v1 aliases. Keep pre-existing /api/v1 routes backward compatible when the web app or other clients already depend on their response shape.

Pagination

New RESTful list endpoints that require pagination must use cursor pagination through query-string parameters:

GET /api/v2/resources?limit=100&cursor=<opaque_cursor>

limit is the number of resources per page. cursor is optional on the first request. When present, it must be the opaque next_cursor value from the previous response.

Responses must use a resource-named collection key plus a sibling pagination object. Do not wrap paginated responses in a generic data key.

{
  "resources": [],
  "pagination": {
    "limit": 100,
    "has_more": false,
    "next_cursor": null
  }
}

Paginated queries must use an explicit, stable order. Prefer newest-first when the resource has created_at, with a unique tie-breaker:

ORDER BY created_at DESC NULLS LAST, id DESC

The pagination object shape is canonical:

"pagination": {
  "limit": 100,
  "has_more": false,
  "next_cursor": null
}

Cursor tokens are opaque, fixed-size, base64url-encoded binary values owned by the API. Clients must pass them back unchanged and must not parse them.

Use snake_case field names in backend responses.