API contract evolution
Include the cost of supporting older clients
Compatibility work extends beyond one adapter. Tests, documentation, data mappings and support all continue while an older contract remains active.
In this article
Identify the supported lifetime
Internal clients deployed together can often migrate quickly. Mobile apps, customer integrations and scheduled jobs may remain on older versions longer. The support policy should reflect those realities.
Estimate the number of contracts and caller versions the team must actively verify. Avoid promising indefinite compatibility without understanding the maintenance obligation.
Keep the reason for a new version concrete. A cosmetic rename may not justify a second long-lived contract if an additive field can preserve behaviour.
Count the recurring work
Each supported contract needs examples, error handling, regression tests and operational knowledge. Changes to the shared business model may require mappings for older representations.
Some mappings are simple. Others become ambiguous when the new domain supports states the old contract cannot express. That complexity can grow over time even if the initial adapter was small.
Include incident diagnosis and customer migration support. A team maintaining several versions needs to identify which contract produced a report and reproduce that caller's behaviour.
Compare alternatives honestly
A coordinated breaking change may be reasonable for a tightly controlled internal system, while an external API may need a longer coexistence period. The choice depends on supported callers and business commitments.
An adapter can reduce duplicated business logic, but it should not silently change the meaning of old fields. If faithful translation is impossible, a clearer migration boundary may be less costly than years of confusing compatibility rules.
Measure use of the old contract and the work needed to migrate its remaining callers. Low traffic can still represent an important monthly process, so involve the owner before assigning it low value.
Budget for retirement as well as introduction
Plan communication, client changes, observation and post-retirement behaviour when introducing the new version. Without that work, temporary support often becomes permanent by default.
Review the policy periodically using actual adoption and maintenance effort. Keep exceptions explicit and owned.
The economical API strategy preserves the compatibility users need while avoiding unnecessary version proliferation. Its cost includes the entire period during which the team must keep old and new meanings working together.
Primary sources
Google AIP-185: API versioningGoogle AIP-180: backwards compatibilityReferences checked 11 September 2026.