Back to Learn
Checklist 5 min read • Updated Jan 2026
The API change checklist for every PR review
Most API regressions are obvious in hindsight. Use this short checklist to catch breaking changes before they hit main.
1. Scope the change
- Which endpoints are touched?
- Is the change additive, or does it remove or rename fields?
- Is there a versioning plan if clients need time to migrate?
2. Validate request contracts
- Are new required parameters introduced?
- Do default values change behavior?
- Are enums or validation rules tightened?
3. Validate response contracts
- Are any response fields removed or renamed?
- Do status codes or error schemas change?
- Do pagination or sorting defaults change?
4. Documentation and examples
- Is the OpenAPI spec updated in the same PR?
- Do docs and examples match the new behavior?
- Is there a migration note for existing clients?
5. Rollout safety
- Is the change behind a flag or staged rollout?
- Are alerts in place for unexpected client errors?
- Is there a rollback plan if issues appear?
Make the checklist automatic
TrueSpec turns the checklist into a CI report so reviewers see breaking changes fast.