| name | ring:designing-api-contracts |
| description | Designing the API contract as a real OpenAPI 3.1 specification (openapi.yaml with full paths, operations, schemas, components, Lerian error envelope, and auth schemes) from the validated TRD. Gate 4 of ring:planning-large-features, Large Track only; runs after ring:writing-trds, before ring:designing-data-model. Use when a system exposes APIs that components or clients consume. Skip for Small Track, a system with no API surface, or an unvalidated TRD. |
API Contract Design — Producing the OpenAPI Spec
When to use
- TRD passed Gate 3 validation
- System exposes APIs (internal or external) that components or clients consume
- Large Track workflow (2+ day features)
Skip when
- Small Track workflow → skip to ring:writing-plans
- No API surface (batch job, library, internal worker) → skip to Data Model
- TRD not validated → complete Gate 3 first
Sequence
Runs before: ring:designing-data-model
Runs after: ring:writing-trds
The deliverable is a REAL, machine-consumable OpenAPI 3.1 spec — not markdown tables. Implementation agents generate handlers, clients, and tests directly from this file. If it doesn't lint, the gate doesn't pass.
Phase 0: API Standards Discovery (MANDATORY)
Check if organizational naming standards exist. See shared-patterns/standards-discovery.md for the complete workflow.
AskUserQuestion: "Do you have a data dictionary or API field naming standards to reference?"
- "No — Use industry best practices"
- "Yes — URL to document"
- "Yes — File path"
If standards provided: WebFetch or read the document and extract:
- Field naming convention (camelCase vs snake_case)
- Standard field names across APIs (createdAt, updatedAt, isActive)
