Day 6 of 60
·
Static analysis & type-time
API spec validation & drift
An API spec is a contract; an API implementation is a fact. The day they diverge silently is the day your consumers start writing tickets neither side can root-cause.
ProblemOpenAPI/AsyncAPI spec and implementation diverge silently.
How it works
Lint the spec; validate at runtime that responses match it; gate PRs on spec change without consumer notification.
What it catches
Spec/code drift bugs that integration tests miss when both sides drift in parallel.
Tools
Spectral · OSS OpenAPI Diff · OSS Schemathesis · OSS Pact Broker · Hybrid
Verdict by project size
Small
Skip
Medium
Rec
Large
Must
Extra-large
Must
Cost
| Project size | Setup | Maint / mo | Tool / mo | CI / run |
|---|---|---|---|---|
| Small <10k LOC | 4h | 1h | $0 | +0.5m |
| Medium 10–100k LOC | 2d | 4h | $0 | +1m |
| Large 100k–1M LOC | 6d | 15h | $200 | +2m |
| Extra-large >1M LOC | 20d | 50h | $1k | +5m |
Setup = engineer-days to first useful run ·
Maint = engineer-hours / month at steady state ·
Tool = out-of-pocket $ / month ·
CI = minutes added (or saved) per pipeline run
Lifecycle & ownership
When in lifecycle
Code Build
Per pull request · Runs in CI on every PR; gates merge.
Who owns it
Developer
Authoring + the inner loop
Collaborates with: Security / AppSec
Reference implementations
-
OpenAPI examples
Canonical API description examples to anchor spec validation and drift checks.
-
Redocly API definitions
OpenAPI starter repository with lintable, reviewable API specs.
-
AsyncAPI examples
Canonical event and messaging API specifications for async contract validation.
Quick check
API spec validation primarily defends against which failure mode?
One question. Pick the best answer. Your streak is saved locally on this device.
Save the lesson
Download SVG ↓
Screenshot for a 1:1, drop it in Slack, or download the SVG.