ROOST projects with HTTP/REST APIs use the OpenAPI Specification (OAS). Projects using gRPC, GraphQL, or event-driven APIs should use their respective native spec formats (Protocol Buffers, GraphQL SDL, AsyncAPI)
P0
Spec location
ROOST convention: spec files live in the repo root or a docs/ directory and are referenced in the README
P0
Spec accuracy
ROOST convention: the spec reflects the current state of the API. Whether the project takes a design-first (spec is source of truth) or code-first (spec is generated from code) approach, spec updates are required as part of any PR that changes API surface
OpenAPI spec is validated in CI (e.g. Spectral, Redocly CLI)
P1
Breaking change detection
CI flags breaking API changes (removed endpoints, changed response shapes). More relevant once projects have downstream consumers depending on API stability (e.g. Osprey post-1.0). Tools: oasdiff, openapi-diff
Document which POST, PUT, and PATCH endpoints are idempotent. Non-idempotent POST endpoints should support an idempotency key to allow safe client retries