API Reliability
API Schema Drift Debugging Guide
Detect API schema drift when fields, types, nullability or nested response shapes change without a coordinated client release. This reference is written for developers who need practical validation behavior, reviewable rules and safe examples rather than copied snippets with no explanation.
Recommended workflow
| Step | Why it matters |
|---|---|
| Preserve both payloads | Keep small redacted examples from the last known-good response and the failing response. |
| Compare structure | Look for renamed fields, number-to-string changes, new null values and arrays that became objects. |
| Find the contract owner | Confirm whether the producer changed intentionally or the consumer relied on undocumented behavior. |
| Add a regression check | Turn the resolved difference into a schema or consumer contract test. |
Starter snippet
capture known-good response -> compare current shape -> classify breaking change -> update contract testReview checks
- Compare field presence separately from field value.
- Review nullable and optional fields explicitly.
- Keep real customer data out of captured payloads.
- Version schema changes with release notes.
Common mistakes
- Comparing only pretty-printed text instead of parsed structure.
- Treating every added field as a breaking change.
- Silently coercing changed types in multiple clients.
Validation should help users correct input while protecting systems from bad data. Keep syntax checks, product policy, security review and deliverability checks separate.
Related Formalint references
Continue with Json Diff, Json Schema Guide, Api Versioning Strategy Guide.