Take the 2-minute tour ×
Programmers Stack Exchange is a question and answer site for professional programmers interested in conceptual questions about software development. It's 100% free, no registration required.

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?

share|improve this question

3 Answers 3

up vote 8 down vote accepted

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.

share|improve this answer
    
Wow, very informative answer –  TheLQ Mar 6 '11 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.

share|improve this answer

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.

share|improve this answer

Your Answer

 
discard

By posting your answer, you agree to the privacy policy and terms of service.

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