Imagine your application depends on a third-party shipping API.
For years, checkout sends an address and package details to the same endpoint and receives delivery options in return. Then the provider announces that the API version is deprecated. A replacement is available, but its authentication method is different, several response fields have changed, and the old endpoint will eventually be retired.
Nothing breaks on announcement day.
Checkout still works.
That apparent stability is what makes API deprecation easy to postpone. The application may continue operating for months while a deadline quietly approaches. Once the provider finally removes the old version, however, an integration that was previously reliable can begin returning errors without your own application having changed.
API deprecation is therefore a maintenance warning: a third-party interface your application depends on is moving toward replacement or retirement.
Google Maps Platform, for example, distinguishes between deprecated functionality—which remains available during a transition period—and decommissioned functionality, which is no longer available. Google says most of its Maps deprecations have a 12-month period before decommissioning.
For Levelworks, this primarily affects Integrable App Health. Current & Updated and Observable also matter because integrations need to move with external services, and teams need enough visibility to know when those integrations begin behaving differently.
This distinction matters.
A deprecated API may still respond normally.
The provider is effectively saying:
This interface should no longer be treated as the long-term way to integrate with our service.
The next stage may be retirement, decommissioning or "sunset," depending on the provider's terminology.
The idea of an API sunset is formal enough that the IETF defined a Sunset HTTP response header in RFC 8594. It allows a service to indicate that a resource is expected to become unavailable at a future point.
Different providers offer different migration windows. Microsoft Graph says generally available APIs are declared deprecated at least 24 months before removal, while Google Maps Platform generally provides at least 12 months' notice for covered services.
The specific deadline varies.
The maintenance lesson does not: deprecation is the beginning of the migration window, not the point at which migration should begin to be discussed.
One reason teams underestimate API deprecation is that "upgrade the API" sounds like changing a URL.
Sometimes it is close to that.
Often it is not.
An API provider may change:
GitHub's current REST API versioning documentation gives a useful definition of breaking changes. Its examples include removing an operation, renaming parameters or response fields, making an optional parameter required, changing field types and changing authentication or authorization requirements.
Suppose your application expects:
{
"customer_name": "Sam Lee",
"status": "active"
}
and the replacement API returns:
{
"customer": {
"name": "Sam Lee"
},
"account_status": "active"
}
The service still provides the same underlying information, but application code that parses the original response can no longer use it unchanged.
A deprecation project therefore needs to identify the contract changes, not merely the new endpoint.
Well-designed APIs often use explicit versions to reduce unexpected breakage.
GitHub's REST API, for example, places breaking changes into new API versions. When a new version is released, GitHub supports the previous version for at least another 24 months. After an API version reaches the end of its support window, requests specifying that closed version receive 410 Gone.
Stripe follows a different model but illustrates the same principle. Its documentation says monthly API releases contain backward-compatible changes, while major releases can contain changes that require application code to be updated. Stripe also provides mechanisms for testing an API version before making the upgrade permanent.
These policies reduce surprise.
They do not make an old integration permanent.
Versioning gives engineering time to migrate deliberately rather than forcing every consumer to adopt breaking changes immediately.
Suppose an API retirement date is six months away.
A team leaves the migration until the final two weeks because the old version continues working.
Then testing reveals that the replacement:
Now engineering has little room to investigate alternatives.
This is why the useful date in a deprecation notice is not only the final retirement date.
You also need an internal migration date that leaves enough time for implementation, testing and production observation.
A reasonable process is:
announcement → impact assessment → migration → parallel validation where possible → production cutover → old API retirement
The provider's deadline should be the outer boundary, not your planned release date.
A mature application may call the same service from several places.
For example, a payment integration might appear in:
Updating only the most obvious call path can leave another workflow dependent on the retired API.
Before migrating, identify:
Question
Why it matters
Which endpoints do we call?
Different endpoints may have different deprecation schedules
Which application workflows use them?
Prevents hidden consumers from being missed
Which fields do we depend on?
Reveals response-contract changes
Which auth scopes or credentials are used?
Detects authorization changes
Are webhooks involved?
Incoming event formats may change too
Which environments use the integration?
Helps validate migration before production
Microsoft's migration guidance for the retirement of Azure AD Graph is a practical example: organizations need to identify both applications and service principals still using the deprecated API before they can complete migration to Microsoft Graph.
[Internal Link: “Why Third-Party Integrations Fail Over Time”]
A successful 200 OK from the replacement API is not enough.
The integration may connect successfully while application behavior is wrong.
Test the scenarios the API actually supports.
For a payment service, that might include successful payments, declined transactions, refunds and webhook processing.
For a mapping service, it might include address lookup, routing and invalid locations.
For an identity API, verify authentication, authorization and relevant account states.
Pay particular attention to:
If the provider offers migration guides or a test environment, use them. GitHub explicitly advises consumers moving to a newer REST API version to review the breaking-change changelog and test the updated integration before completing the upgrade.
API migration is not finished when the code reaches production.
Watch the integration for differences that test environments may not reveal.
Useful signals include:
If an integration suddenly begins returning more validation errors after migration, that is useful evidence even when the provider itself remains available.
This is where Observable App Health supports Integrable. Third-party integrations need enough monitoring that a contract problem can be distinguished from an application bug or provider outage.
[Internal Link: “How to Monitor the Health of Your App’s APIs and Integrations”]
Google Maps Platform may provide substantial deprecation periods for covered services, while Microsoft Graph publishes its own support policy and GitHub uses version-specific support windows. Providers can also have exceptions for security, reliability or low-usage functionality.
The application team therefore needs to know where change announcements arrive.
That may mean monitoring:
Make sure those notifications go to a maintained team address rather than the inbox of the developer who originally created the integration five years ago.
[Internal Link: “API Security Maintenance: How to Keep Integrations Secure Over Time”]
A third-party API gives an application capabilities it does not need to build itself.
The trade-off is that the provider controls part of the interface.
It can introduce a new version, retire an endpoint, change authentication requirements or replace a feature. Good providers normally communicate and version those changes carefully, but the responsibility for adapting your application remains yours.
That is why Levelworks treats API lifecycle management as part of Integrable App Health.
A healthy integration is not merely one that works today. It is one whose dependencies are known, whose provider changes are being watched, and whose migration path is addressed while there is still time to test it properly.
When an API is deprecated, the important question is not:
“Does the old endpoint still work?”
It is:
“What must change before the day it no longer does?”
