← ClaudeAtlas

api-contract-designlisted

Designing and evolving service contracts: HTTP method and status semantics, RFC 9457 problem errors, cursor pagination, idempotency keys, ETag concurrency, additive evolution and deprecation headers, OpenAPI 3.1/TypeSpec and protobuf/gRPC rules, breaking-change gates (oasdiff, buf) and client/server code generation from specs with drift checks. Load when adding or changing an endpoint, RPC, event schema or SDK.
rustcircle/c101 · ★ 0 · API & Backend · score 65
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