In this article
A deprecation notice communicates interface lifecycle; actual behavior changes need separate versioning and validation.
Inventory the observable contract
An inference API contract includes JSON fields, HTTP behavior, streaming order, terminal states and parameter semantics. An engine update can affect that layer without changing an endpoint path. Preserve the current version description and representative client scenarios before release. OpenAPI 3.1.1 can pin the interface description, while SSE temporal properties need additional fixtures. A migration should expose a concrete diff and its consequences for consumers. Calling an API compatible without naming tested properties does not explain why an older parser will keep working or which changes a client must handle after the service update.
Classify changes
Removing a required field, changing a type or introducing an enum value can break strictly validated clients. Even adding a field is not always harmless when a client rejects additional properties. The JSON Schema object reference explains required properties and extension rules; these settings matter when assessing actual compatibility. Missing values and null also differ. Record the old response, new response and affected client class for each change. A compatibility claim should refer to a defined consumer model, rather than every possible library. A semantic change with an unchanged type deserves as much attention as an obvious schema difference.
Use Deprecation for its intended purpose
RFC 9745 defines the Deprecation header and ways to provide related information. A notice does not itself mean the resource’s behavior changes immediately. Separate it from an actual retirement date and from concrete migration instructions. A service policy should describe the affected version, reason, replacement and documentation location. This is designing a service’s own policy, rather than asserting that OpenRouter follows this practice. A date without scope offers little help. If only one streaming mode is affected, wording should make that clear without suggesting that the entire API or every model is being discontinued together.
Exercise both sides of migration
A small corpus checks the old client against old responses, the old client against new responses, and an updated client against both permitted forms. For SSE, separately test additional frames, changed ordering and unknown fields. Fixtures should capture properties rather than literal generated prose. Begin diagnosis at the failure location: schema validation, event parsing or terminal state interpretation. Then decide whether the change needs an endpoint version, an overlap period or a client adaptation. Simply updating golden files and declaring success can erase the very evidence of incompatibility the pre-release check was intended to discover.
Preserve the decision and tested scope
The release artifact contains the contract diff, client matrix, approved exceptions, migration example and rollback conditions. See model update canaries and the software stack record. A canary samples selected traffic but does not replace protocol checks for rare scenarios. A successful migration means the listed clients and fixtures passed in the specified environment. It is not a universal guarantee for unknown integrations. After release, continue observing parse failures and older version distribution without putting user identifiers in metric labels. This makes the change’s consequences measurable while preserving clear boundaries around the compatibility promise.