Eventually you need to depreciate parts of your public web API. However I'm confused on what would be the best way to do it. If you have a large 3rd party app base just yanking old versions of the API seems like the wrong way to do it as almost all apps would fail overnight. However you can't keep ancient web api's available forever as it might be outdated or there are significant changes that make working with it impossible.

What are some best practices for deprecating old web api's?

4 Answers 4


It sounds like the original poster has already effectively, but informally deprecated their API (anything that is referred to as 'old API'). However, until it is announced and users are notified that an API is deprecated, it is not formally deprecated.

Deprecated API is an interim, inactive stage of code. It is the last rites. This is the period that allows adopters/consumers to reconfigure their apps for a newer API and bid a fond farewell, making peace with the API. Some APIs may linger longer than others, but at this point we know their time isn't long.

Deleted API is a code funeral. There is nothing more that it can do, but properly disposed and appropriately memorialized.

Many API and service developers opt for code funerals rather than performing last rites; however, I think that is somewhat risky. If there was any kind of service or support promise made when the API/service was either initially adopted or through renewal, you may want want to honor that committment for a reasonable period of time before performing the funeral.

For non service libraries, I think one major release version, regardless of the period of time, is probably a more than acceptable and fair period of guaranteed backwards compatibility. Beyond that it depends on the influence and lobbying by users to extend it's life beyond that period. And don't be suprised if from time to time there are objections due to irreplacable 3rd party dependancies being stuck in limbo, and tied to certain versions of certain platforms.

For services, I suspect you might want to look at either a six month or year period, simply because of the variance in by who and by how a service can be consumed, and the corresponding development cycle variance from consuming project to consuming project -- many projects that might be consuming your service could still big up-front design, and may schedule a release cycle of longer than a year. Most developer opinions from the outside would suggest that those with long schedules are responsible for meeting your cycle times, and those long cycle consuming projects should adopt a quicker release cycle, and it may be true. But ultimately the date of deletion is something that you have to negotiate with users.

A good but not bulletproof strategy for deprecation might be when annoucing deprecation, highlight the timeframe for intent to delete, along with a request for comment or objection in a survey format of the API sections in question. If you don't have a contact list of users because your service operates with [semi] anonymous access, you might consider looking at logs for frequent and active users and dispatch the notification to the host or domain administrator to forward as they see fit.

  • Wow, very informative answer
    – TheLQ
    Mar 6, 2011 at 2:34

Most of the Web API's I use (from companies like Google, Yahoo! and Microsoft) have a "sunset" period. Developers are informed within a reasonable time (say 3-6 months) of the features that are going to be depreciated to give them plenty of time to upgrade beforehand.

You can add the details of sunset periods in your Terms of Service or other documentation so people are aware about how it works. This would mean that when someone decides to use your API they will know what schedules they need to work with. For example, you could inform people that they will need to upgrade their system once a year and have 4 months notice to do so.

It's also a good idea to use version numbering so you can say that, for example, "version 3 is going to be depreciated soon so make sure your code works with version 4" etc. That way people know that if their application's working with version 4 then they're ready for the sunset.


Additional information from process angle:

  • Communicate with all stakeholders: Provide to other teams and API consumers a clear and concise communication about the reason to deprecate the API, the strategy, the plan and schedule details, versioning meaning, and alternatives, set the HTTP accordingly.

  • Plan and Schedule: On the plan you should have the key milestones and target date for deprecation end. You should ask consumers to the same and provide dates when they will deprecate the call. Host a regular meeting to monitor the process and support the consumers.

  • Versioning and Provide Alternatives: The versioning may help to show break changes on major releases, and make the strategy of API deprecation.

  • Set the Sunset HTTP Response Header: The HTTP headers play the technical part of the warning, API consumers should monitor this type of code to understand the when an API is getting deprecated.

  • Monitor Before and After: Monitor your consumers and alert any consumer that still using the API after a certain period is useful information to ensure you do not miss any abandonware.

  • 1
    Upvoted for info on the Sunset Response Header. First time I hear about this one and after reading more on it it seems incredibly useful.
    – julealgon
    Jul 30, 2020 at 15:44

In addition to the existing answers, you should provide a drop-in replacement or a migration plan when removing something, so your users can update their code.

Try to avoid removing functionality without providing an alternative - this would make some of your users unhappy.

  • If it's possible in your web API, keep the deprecated functions active, but have them return an informative error, rather than just breaking. Jun 14, 2016 at 17:32

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.