API Reliability
OpenAPI Breaking Change Checklist
Review OpenAPI changes for removed operations, stricter inputs, response shape drift and generated-client impact before 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 |
|---|---|
| Diff parsed specifications | Compare operations, parameters, schemas and response codes structurally rather than line by line. |
| Check stricter inputs | A new required field, narrower enum or smaller limit can break existing callers. |
| Check response compatibility | Removed fields, changed types and newly nullable values affect generated and handwritten clients. |
| Prove the migration | Run consumer tests and publish examples before deploying the producer change. |
Starter snippet
baseline spec -> structural diff -> classify client impact -> run contract tests -> publish migration noteReview checks
- Resolve references before comparing schemas.
- Review default and nullable semantics.
- Include authentication and server URL changes.
- Version generated SDKs with the contract.
Common mistakes
- Calling every additive schema change safe.
- Reviewing only endpoint paths.
- Publishing a changed spec after code is already live.
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 Openapi Contract Checklist, API Schema Drift Debugging, Api Versioning Strategy Guide.