API contract evolution
Measure use of the contract you want to retire
Request counts are a starting point. Identify active callers, their business cycles and the operations still depending on the old contract before setting a retirement decision.
In this article
Attribute traffic to a caller
Record API version, operation and a suitable client or integration identifier. Avoid using sensitive request contents as the identification mechanism.
Distinguish production callers from test traffic and internal probes. A large volume from one monitoring job can obscure a small but important business integration.
Keep unsuccessful requests in the view. A caller broken by the candidate may stop producing successful traffic, which should not be mistaken for successful migration.
Use a meaningful observation window
A client that runs monthly or during a seasonal process may be absent from a week's logs. Choose the window according to supported business use and confirm ownership where traffic alone cannot establish retirement readiness.
Track last use and the operations called, not only total volume. An integration may have migrated most endpoints while retaining one critical old operation.
Identify unknown callers as unresolved work. A deprecation plan is weak if the team cannot contact or otherwise account for the remaining supported users.
Measure migration outcomes
For upgraded callers, compare error rates, latency and business completion. Adoption of a new version header does not prove the integration handles changed defaults or pagination correctly.
Use contract tests and representative workflows to verify behaviour. A caller can send valid requests while silently ignoring new pages or misinterpreting a field's units.
Track support incidents and rollback to older clients. These signals reveal whether migration guidance or compatibility adapters are incomplete.
Define the retirement gate
Combine observed use, owner confirmation and successful workflow checks. Document any accepted exceptions and their expiry rather than relying on a single zero-traffic chart.
Keep a clear response for calls arriving after retirement, with the supported migration information appropriate to the API. Do not leave an old route returning an unrelated generic page that callers cannot interpret.
The evidence should establish that the old contract is no longer required by supported business work, or that its remaining users have an explicit transition decision. Low volume alone does not make a dependency unimportant.
Primary sources
Google AIP-185: API versioningGoogle AIP-180: backwards compatibilityReferences checked 11 September 2026.