api-contract-designlisted
Install: claude install-skill rustcircle/c101
# API contract design
The contract is the spec file, not the code. Design and review the spec diff first; code and
clients follow from it. Review-time checks for an existing diff stay in `code-review-checklist`
("API design and compatibility"); this skill is how to design the contract those checks verify.
Test levels and strategy are in `testing-strategy`; auth and injection review in `security-review`.
Standards referenced (verified October 2026): RFC 9110 (HTTP semantics), RFC 9457 (problem
details, obsoletes 7807), RFC 9745 (Deprecation header, March 2025), RFC 8594 (Sunset), RFC 8288
(Link), RFC 3339 (timestamps), OpenAPI 3.1 (JSON Schema 2020-12; OpenAPI 3.2 was published
September 2025, check tool support before adopting it). The Idempotency-Key header is an IETF
draft (draft-ietf-httpapi-idempotency-key-header-07, expired, not an RFC); its semantics are
widely implemented anyway.
Deep material:
[OpenAPI components and lint rules](references/openapi-components.md) |
[code generation and CI gates](references/codegen-and-ci-gates.md)
## 1. Spec-first workflow
1. Write or change the contract: OpenAPI 3.1 YAML, TypeSpec (`tsp compile . --emit @typespec/openapi3`),
or `.proto`.
2. Lint: `npx @redocly/cli lint openapi.yaml`, or `npx @stoplight/spectral-cli lint openapi.yaml`
with a team ruleset; `buf lint` for protobuf.
3. Breaking-change gate against main (section 8).
4. Review the contract diff with consumers before writing handlers.
5. Generate server stubs/type