ring-designing-api-contracts

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)