Versioning
We version in the URL path (/v1/) rather than headers. It is explicit and cacheable.
Error format
{ "error": { "code": "NOT_FOUND", "message": "Resource not found", "request_id": "abc123" } }Pagination
Cursor-based pagination by default for any list endpoint that may grow unbounded. Offset pagination only when the client genuinely needs random-access page jumps.
Auth
JWT with short expiry + refresh token rotation. API keys for server-to-server. OAuth 2.0 for third-party integrations.