When managing an API, eventually there comes a time when you need to retire or deprecate an old API version in favor of a newer one. Deprecating an API version is a normal part of the API lifecycle and allows you to upgrade and improve your API without negatively impacting existing users. However, deprecating an API version requires careful planning to ensure a smooth transition.
When to deprecate an API version
There are a few common reasons you may want to deprecate an API version:
- The API version contains bugs, security vulnerabilities, or design flaws that need to be fixed
- You want to add new features, resources, or capabilities to the API
- Significant backend implementation changes make supporting the old API version difficult
- Usage of the API version has declined over time
- The API version is very old and continuing to support it slows development of the overall API
As a general rule of thumb, you should consider deprecating an API version once it is two or more years old, or if usage drops below 5% of total API traffic. However, there are no hard and fast rules – the decision depends on your specific circumstances.
How to deprecate an API version
Once you decide to deprecate an API version, there are a few key steps to follow:
- Announce the deprecation – Give API consumers significant advance notice, at least 6 months if possible. Announce the deprecation through channels like email, docs, status pages.
- Monitor usage – Track usage of the deprecated version to understand adoption and prepare for its retirement.
- Enforce a sunset period – Continue supporting the deprecated version for a defined period, usually 3-12 months, before fully retiring it.
- Remove references – Update documentation and code samples to point users to the newer API version.
- Retire the deprecated version – After the sunset period ends, shut down the deprecated API version and return 410 Gone status codes.
Following this process helps consumers smoothly transition to newer API versions before support ends. Be sure to clearly communicate timelines and provide migration guidance.
Communication during deprecation
Communication is key when deprecating an API version. At a minimum, you should communicate the following information to users:
- Which API version is being deprecated
- When the deprecation takes effect
- The sunset period and final retirement date
- Guidance on migrating to newer API versions
- Who to contact with questions
Some best practices for communication include:
- Announce early and repeat often across channels
- Be transparent about rationale and timelines
- Provide migration guides with code samples
- Highlight benefits of upgrading
- Offer developer support during migration
The more proactive and helpful you can be, the less disruptive the deprecation will be for users.
Versioning best practices
To minimize the need for disruptive deprecation in the future, follow API versioning best practices from the start:
- Use semantic versioning – e.g. v1, v2, v3
- Namespace versions in URLs – e.g. v1.api.example.com
- Support multiple versions in parallel
- Avoid breaking changes in minor versions
- Set a version lifecycle policy
- Use deprecation headers before retiring versions
With proper API versioning, you can iterate and improve your API without breaking existing consumers. Be sure to communicate any versioning policies to developers.
Alternatives to versioning
In some cases, you may want to avoid having multiple API versions altogether. Some alternatives to consider include:
- Full backward compatibility – Never remove or modify existing fields, only add new fields/capabilities.
- Feature flags – Use flags to control rollout of new features, keeping a single API version.
- Separate regional endpoints – Deploy changes to new regions first, avoiding impact to existing regions.
These approaches prevent fragmentation across API versions. But it can be difficult to maintain extensive backward compatibility long-term.
Handling versioning with REST vs SOAP vs GraphQL
API versioning details vary across architectural styles:
REST
- Leverage HTTP headers for versioning – e.g. Accept-version
- Version number in URL is common – e.g. https://api.example.com/v2/users
- Avoid changes that modify HTTP methods, status codes, or headers
SOAP
- Version number goes in XML namespace – e.g. http://example.com/v2
- Wsdl documents are versioned for each release
- Avoid changes that break XML schema compatibility
GraphQL
- Version through schema introspection
- Use directive @deprecated for deprecated fields
- Avoid changes that break existing queries
The versioning approach should align with conventions for the API style you are using.
Choosing a sunset period duration
When deprecating an API, the sunset period is the length of time you continue supporting the deprecated version before retirement:
Sunset Period | Recommendation |
---|---|
Less than 3 months | Only for emergency removals due to security issues or regulartory requirements. Otherwise not enough time for most consumers to migrate. |
3 to 6 months | Typical for deprecating minor API versions. Gives consumers time to update their integrations. |
6 to 12 months | Recommended when deprecating major API versions. Provides ample migration time for consumers. |
Over 12 months | Generally not needed. Extends support overhead for you as the API provider. |
Consider usage levels, complexity of required changes, and other factors when choosing an appropriate sunset period. A longer sunset allows more consumers to migrate smoothly.
Metrics to track during deprecation
Use metrics to guide the deprecation process. Key metrics to track include:
- Usage of deprecated version – Monitor to understand adoption and inform sunset period length.
- Errors from deprecated version – Rising errors may signal integration issues needing assistance.
- Usage of new version – Ensure growing adoption of the new API during deprecation.
- Performance of new version – Monitor for any scaling issues under increased load.
- Documentation views – Verifies your deprecation notices and migration docs are being seen.
Tracking these metrics provides visibility into how the deprecation is progressing and where consumers may need help migrating.
Impact on SDKs and tools
In addition to working with consumers directly integrating your API, consider impacts to related SDKs, tools, and packages:
- Update SDKs to new API version, provide upgrade guide
- For popular tools, contact authors about deprecation plan
- If you maintain API client libraries, release new versions aligned to API changes
- Monitor GitHub for deprecated API references in open source tools and notify owners
Helping SDKs, tools, and client libraries transition to the new version improves the deprecation experience for all API users.
Handling API keys and quotas
API keys and usage quotas should be transferred carefully during a deprecation:
- Allow existing API keys to work on both versions during sunset period
- Inform consumers their keys will only work on new version after cutoff date
- Apply old version usage quotas to new version as well to avoid surprises
- Monitor for suspicious traffic spikes from invalid keys after retirement
With planning, you can migrate API authentication smoothly and avoid inadvertent service disruptions.
Legal and regulatory obligations
Consider any legal and regulatory requirements when planning an API deprecation:
- Review contracts and SLAs for notice period and support obligations
- For regulated industries like healthcare, ensure compliance processes are followed
- If users have paid for API access, you may be obligated to provide refunds
- For platforms and partner programs, adhere to any deprecation policies and processes
While rare, some organizations may have special constraints around API lifecycles. Do your diligence to avoid surprises.
User notification examples
Here are some examples of effective user notifications when deprecating an API version:
Email notification
Subject: Action required: API v1 deprecation notice
Body: We will be deprecating API v1 on March 1, 2023. Please migrate to API v2 as v1 will be retired on September 1, 2023. For details and migration instructions, visit: https://example.com/v1-deprecation
In-app notification
Title: API Update Required
Body: Heads up, API v1 will be deprecated on March 1, 2023. Please migrate to v2. Get migration help here. Contact [email protected] with any questions.
Documentation site notice
A banner announcing the deprecation timeline and linking to a migration guide page with details and code samples for upgrading.
Conclusion
While requiring some upfront effort, thoughtfully deprecating API versions allows you to improve and evolve your API over time without disrupting consumers. Follow best practices like semantic versioning, set clear timelines, communicate changes proactively, and help consumers upgrade to new versions. With adequate planning and support, you can sunset old API versions smoothly and successfully.