This FRD covers authoring, reviewing, and ratifying ADR-061, which will codify the platform’s API design standards: request/response shape conventions, versioning strategy, error envelope format, pagination patterns, and idempotency key requirements. The ADR formalizes patterns already partially expressed in src/lib/api-types.ts and the api-shared-contract.mdx guide, making them enforceable and discoverable.
Introduction
Overview
The platform has ad-hoc API conventions scattered across code (src/lib/api-types.ts), a shared-contract guide (docs/devops/guides/api-shared-contract.mdx), and tribal knowledge. No single ADR governs API design decisions. This creates ambiguity when building new endpoints: developers must reverse-engineer conventions from existing code. ADR-061 will be the authoritative reference for all API design questions.
Goals
Define the canonical request and response shapes for all platform APIs.
Specify the versioning strategy (URL path vs. header, breaking-change policy).
Codify the error envelope schema (matching apiErrorSchema in api-types.ts).
Standardize pagination (cursor-based and offset-based, matching paginationSchema).
Require idempotency keys for all mutating endpoints.
Link the ADR to src/lib/api-types.ts as the TypeScript source of truth for these shapes.
Non-Goals
Implementing new API endpoints (ADR is governance, not implementation).
Defining authentication or authorization patterns (covered by ADR-025).
Specifying API integration/client patterns (covered by ADR-062).
Scope
In Scope
Item
Description
ADR-061 MDX document
Full ADR following the project’s ADR template with frontmatter tags.
Request shape conventions
Standard envelope for request bodies, query parameter naming.
Response shape conventions
Success envelope ({ data } for single, { data, pagination } for lists), error envelope (ApiError).
Versioning strategy
URL path prefix (/v1/), header-based negotiation for minor versions.
Error envelope
Codifies apiErrorSchema from api-types.ts: code, message, details, request_id.
Pagination
Cursor-based (primary) and offset-based (fallback), matching paginationSchema.
Idempotency keys
Idempotency-Key header required on POST/PUT/PATCH, with server-side deduplication semantics.
ADR routing update
Regenerate docs/adrs/docs-index.json and Storybook Docs/ADRs/Overview.
Out of Scope
Item
Reason
Client-side API integration patterns
Covered by ADR-062.
Rate limiting design
Infra concern, not API shape.
Authentication headers
Covered by ADR-025.
GraphQL or gRPC conventions
Platform uses REST; other protocols are not currently in scope.
Users and Pain Points
User
Pain Point
Backend developer
No authoritative reference for how to structure a new endpoint’s request/response. Must copy patterns from existing code.
Frontend developer
Inconsistent error shapes across endpoints force per-endpoint error handling rather than a shared error boundary.
API reviewer
No ADR to cite when requesting changes during code review; conventions are implicit.
Platform maintainer
Versioning strategy is undocumented, making breaking-change decisions ad hoc.
Definitions
Term
Definition
Error envelope
The standard JSON shape returned for all 4xx and 5xx responses, defined by apiErrorSchema.
Idempotency key
A client-generated unique identifier sent via the Idempotency-Key header to ensure that retried mutating requests produce the same result.
Cursor-based pagination
Pagination using an opaque next_cursor token rather than page numbers. Preferred for large or frequently changing datasets.
ADR
Architecture Decision Record. An immutable document capturing a design decision, its context, and consequences.
Current State
src/lib/api-types.ts defines Zod schemas for ApiError, Pagination, and paginatedResponseSchema. The docs/devops/guides/api-shared-contract.mdx guide describes the shared contract informally. However:
No ADR exists to make these conventions enforceable.
The versioning strategy is not documented anywhere.
Idempotency key requirements are not specified.
Query parameter naming conventions (snake_case vs. camelCase) are inconsistent across endpoints.
Error code values are not enumerated or governed.
Proposed Solution
Author docs/adr-061-api-design.mdx with the following sections:
Context — The platform exposes REST APIs consumed by the design-system frontend. Consistent shapes reduce integration friction and enable shared error handling.
Decision — All APIs follow the conventions below.
Request conventions — JSON request bodies use camelCase keys. Query parameters use snake_case. Array parameters use bracket notation (ids[]=1&ids[]=2).
Versioning — Major version in URL path (/api/v1/). Minor/patch changes are backward-compatible and do not require a new path. Deprecation communicated via Sunset header.
Pagination — Cursor-based by default (next_cursor in response, cursor query param). Offset-based fallback (page and page_size query params) for simple use cases. Both shapes match paginationSchema.
Idempotency — All POST, PUT, and PATCH requests must accept an Idempotency-Key header. The server stores the response for a key and returns it on retry within a 24-hour window.
Consequences — All existing endpoints must be audited for compliance. New endpoints must pass review against this ADR.
The ADR frontmatter will include:
tags: [api, api-design]
applies_when: "Building or reviewing any REST API endpoint"
status: ratified
Requirements
ID
Priority
Requirement
API61-01
P0
ADR-061 MDX file created with full ADR template and frontmatter.
API61-02
P0
Request and response shape conventions documented with examples.
API61-03
P0
Error envelope specification matches apiErrorSchema from api-types.ts.
API61-04
P0
Pagination conventions documented for both cursor-based and offset-based.
API61-05
P0
Versioning strategy documented (URL path prefix, Sunset header for deprecation).
API61-06
P0
Idempotency key requirements documented.
API61-07
P1
ADR index updated with ADR-061 entry.
API61-08
P1
Cross-reference from api-types.ts TSDoc to ADR-061.
Functional Requirements
The ADR must include at least one request and one response example in TypeScript for each convention (single resource, list, error).
The ADR must specify the exact Content-Type header expected (application/json).
The ADR must list the canonical HTTP status codes for success (200, 201, 204) and error (400, 401, 403, 404, 409, 422, 429, 500).
The ADR must define the format of error code strings (dot-separated namespace, lowercase).
The ADR must specify that request_id is generated server-side and included in both success and error responses.
Non-Functional Requirements
Category
Requirement
Discoverability
ADR frontmatter tags include api and api-design so routing table lookups work.
Consistency
All conventions must align with existing api-types.ts schemas. Conflicts require updating the code, not the ADR.
Enforceability
Conventions must be specific enough to serve as a code-review checklist.
API/Interface Requirements
The ADR itself defines API interface requirements. No code API changes are introduced by this FRD; the ADR codifies existing patterns.
Accessibility Requirements
Not applicable. This is a governance document, not a UI component.
Content and Documentation Requirements
ADR-061 written as docs/adr-061-api-design.mdx following the project ADR template.
docs/adrs/docs-index.json and Storybook Docs/ADRs/Overview updated with ADR-061.
CLAUDE.md routing table already maps api tag to ADR-061; verify after creation.
TSDoc @remarks in api-types.ts updated to reference ADR-061.
Dependencies
Dependency
Type
Notes
src/lib/api-types.ts
Internal
Existing schemas that the ADR codifies. Must stay in sync.
docs/devops/guides/api-shared-contract.mdx
Internal
Existing informal guide; ADR-061 supersedes it for normative decisions.
ADR-025
Governance
Auth-related API conventions are deferred to ADR-025.
ADR-062 (pending)
Governance
Client-side integration patterns will reference ADR-061 shapes.
Risks and Tradeoffs
Risk
Likelihood
Impact
Mitigation
Existing endpoints do not conform to the ADR.
High
Medium
ADR includes a “compliance timeline” section giving existing endpoints two release cycles to conform.
docs/adrs/docs-index.json and Storybook Docs/ADRs/Overview include ADR-061.
src/lib/api-types.ts TSDoc references ADR-061.
pnpm build-storybook passes (MDX renders without errors).
LLM Handoff Instructions
When implementing this FRD:
Use the project’s ADR template. Check an existing ratified ADR (e.g., docs/adr-025-identity-auth-and-secrets.mdx) for the expected structure and frontmatter format.
Create docs/adr-061-api-design.mdx with frontmatter: tags: [api, api-design], applies_when: "Building or reviewing any REST API endpoint", status: ratified.
Reference the Zod schemas in src/lib/api-types.ts directly. The ADR must not contradict those schemas.
Include TypeScript code examples for: a single-resource response, a paginated list response, an error response, and an idempotency key header.
Run pnpm run docs:index and pnpm run adrs so ADR-061 appears in machine-readable routing and the Storybook overview.
Add @remarks Governed by ADR-061. to the TSDoc for apiErrorSchema, paginationSchema, and paginatedResponseSchema in api-types.ts.
Run pnpm build-storybook to confirm the MDX renders.
Decision Log
Date
Decision
Rationale
2026-05-26
URL path versioning over header versioning.
Simpler for clients, easier to route at the gateway level, widely adopted convention.
2026-05-26
Cursor-based pagination as primary, offset as fallback.
Cursor-based avoids skip-scan performance issues on large datasets. Offset remains available for simpler use cases.
2026-05-26
24-hour idempotency key TTL.
Balances storage cost against retry windows for long-running operations.