DOCUMENTATION / API COMPATIBILITY
How to detect API contract drift before it breaks consumers
By Soumik Ghosh ยท Published
API contract drift is the gap between the interface a consumer expects and the contract or behavior available upstream.
Capture the contract your consumer actually uses
Record the source URL, fetch date, declared version, and content hash. An upstream specification can change while keeping the same version. Check runtime observations separately and avoid assuming that every documented change has already deployed.
From contract changes to affected callers
- Compare two revisions and identify the changed operation, field, and direction.
- Trace the operation into supported SDK and HTTP call sites at the scanned commit.
- Review matching limits and replay representative requests and responses before merging any change.
See how a removed Sentry query value changes request acceptance, or replay a finding in the OpenAPI checker.
API compatibility guides and tools
- GraphQL breaking changes in schemas and operations
- gRPC and Protobuf breaking changes
- AsyncAPI breaking changes in events and messages
- SOAP and WSDL breaking changes
- Self-healing API integrations with checked migration drafts
- How to detect API contract drift before it breaks consumers
- oasdiff and API code impact analysis answer different questions.
- Detect breaking API changes in a GitHub workflow.
- Why a TypeScript build can pass after an API changes.
- OpenAI OpenAPI breaking changes: a captured response change.
- Sentry OpenAPI breaking changes: removed replay query values.
- Inspect classification rules interactively
- Check captured OpenAPI changes
- Compare JSON Schemas
- Plan your business evaluation
Use public API change evidence in your IDE with MCP
Browse public API change history, including OpenAI and Sentry.
Rule reference
schema.request_acceptance_narrowed: Request schema accepts fewer valuesoperation.endpoint_removed: Endpoint removed from the contractrequest.content_removed: Request media type removedlevel.error: Detector error falls back to breakingrequest.enum_removed: Request enum value removedrequest.now_required: Request property becomes requiredresponse.removed: Response property removedresponse.now_optional_or_nullable: Response property becomes optional or nullablerequest.removed_unknown_strictness: Request property removed, server strictness unknown