api-contract

API Contract

An API is a promise. This skill ensures that promise is explicit, versioned, and broken only deliberately. It covers design, documentation, versioning, and the process for managing changes that affect consumers.

When to Use

• Designing a new HTTP API or adding endpoints to an existing one
• Reviewing a PR that modifies request/response shapes, status codes, or auth requirements
• Planning a breaking change to an existing API
• Onboarding consumers (frontend, mobile, other services) to an API
• Before releasing a new API version

When NOT to Use

• Internal function signatures or module interfaces — this skill is for network-boundary APIs
• gRPC or GraphQL (different contract mechanisms — see graphql skill when available)
• Database schema changes — use migration-strategy

Core Principles

Contract-First, Not Code-First

Design the API contract before writing implementation. The OpenAPI spec is the source of truth — not the code, not the documentation, not the Postman collection. If they diverge, the spec wins until the spec is deliberately updated.

Backward Compatibility is a Hard Constraint

Once an API endpoint is consumed by any external client, any change that breaks existing consumers requires a version bump. The cost of breaking consumers silently is always higher than the cost of versioning.

Every Endpoint is a Public Commitment

Design as if the endpoint will be consumed by a party you cannot contact. Document every field, every status code, every error case — because absent documentation, consumers will hardcode assumptions about your implementation details.

API Contract Process

Use the checklist below and track progress:

API contract progress:
- [ ] Step 1: Design contract in OpenAPI spec before implementation
- [ ] Step 2: Apply API design standards
- [ ] Step 3: Define error contract explicitly
- [ ] Step 4: Assess backward compatibility impact
- [ ] Step 5: Version if breaking changes are required
- [ ] Step 6: Update deprecation markers and consumer communication