Part 9 · 1 chapters · ~8 min
Contract Testing and API Governance
Provider contract tests against the spec, consumer-driven contracts with Pact, breaking-change detection in CI (oasdiff, buf breaking), API linting with Spectral and a style guide, review boards that help rather than block, and an API catalogue.
16
Tests and governance that scale
code
# CI for an API change spectral lint openapi.yaml --ruleset .spectral.yaml # style guide: naming, errors, pagination, ids oasdiff breaking main:openapi.yaml HEAD:openapi.yaml --fail-on ERR # block breaking changes without a version bump schemathesis run openapi.yaml --base-url http://localhost:8080 # implementation matches the spec pact-broker can-i-deploy --pacticipant transfers --version $SHA --to production # consumers' contracts satisfied
| governance practice | purpose |
|---|---|
| an API style guide encoded as lint rules | consistency without meetings |
| design review for new public resources | catch modelling mistakes while they are cheap (before clients exist) |
| an API catalogue (Backstage, a portal) | find existing APIs before building duplicates; owners and status visible |
| breaking-change gates in CI | no accidental breaks; intentional ones need a version and a plan |
The staff-level move: make the paved road the easy road. A template service with the spec, lint rules, error format, pagination helper and SDK pipeline already wired in does more for consistency than any review board.