Should APIs Always Be Backwards Compatible?

Do you live in the now or keep a foot back in the past? Better yet, what should an API provider do?

At the end of July shut off some old API calls, to the disappointment of some mashup users and developers (our API profile). The company had some good reasons, but it raises the question about what developers should expect, especially from free APIs.

While the changes were announced in March, giving plenty of warning to developers, it is inevitable that some mashups wouldn't be fixed. Indeed, there are a host of applications that can no longer be written using the API.

Carson Ball explains one way the change is noticed by users:

"The changes that made were not backwards compatible and caused software that used the API to break. The open source music player Banshee for instance still displays recommended tracks from, but is unable to play these tracks. When a user attempts to listen to a recommended track, he or she is greeted with the message 'GStreamer resource error: NotFound' on the terminal or in the error log. In light of this error, displaying the tracks at all is rather pointless."

In this case, it seems had good reason to make the change. The streaming API was never documented or released, though the company did not stop it from being developed upon. Since copyrighted music is played through the undocumented API, still had to pay for what developers used. There were real business and legal reasons for the API change.

Mature APIs like the API, eBay API, and the Amazon Product API go to great lengths to address this issue via processes such as consistent release cycles and/or maintaining availability of old versions for long periods of time, even years.

Do you think APIs should always be backwards compatible? What's the best approach when something needs to change?

Be sure to read the next Law article: Find The Words With ChartLyrics Lyric API


Comments (6)


An API should encompass graceful degradation right in it from the start. For example, returning a flag saying that this or that call is deprecated and will be unsupported soon would be a good idea, if somebody is using deprecated calls. Support for old calls does need to be continued for a while, giving developers time to change their software. Simply cutting the functionality immediately doesn't hurt those developers as much as it directly impacts your users.

Twitter has done this to me and several others in the past, they simply dropped support for several critical API calls without any warning or notification of any sort. It's one reason I refuse to develop for the Twitter API any longer, it is not a reliable API and their developer team is wholly unresponsive to feedback.


Yes they should. This is something Microsoft always got right. Event the iPhone and OS-X gets this right.

You want people to use your service or API and they go build products based on it. There is no way you can possibly know all of the products that are using your API. You can't simply break them.

What if TiVo was using a 3rd Party Guide API and one day, without knowing who used the Guide API, they simply changed it - semantics, a parameter, the output, whatever it maybe - then TiVo stopped working for its millions of customers. Completely unacceptable.

It's worth noting that the last time we shut off a publicly-released, documented API was in 2004.

We care a lot about API compatibility, and the fact that our legacy streaming APIs were not officially supported reflected our reservations about this.

The beauty of SAAS is that you can actually see who is using your features. We had to migrate a couple of clients from an old set of functions and we managed to do it in a graceful way - #1 add logging and see who is accessing that particular endpoint, #2 reach out to the application developers, #3 give them reasonable time to make changes.

When people say: "API should never change" I believe they are saying - "I hate surprises and additional work I didn't anticipate". I think in the business world everyone is realistic about the fact that services evolve and when you pick a SAAS vendor you will have to do some work in the future - it could be to take advantage of new features or stop using deprecated ones.


I think that if an API was inherently insecure (assuming security mattered in this context) then it should be changed. In many cases though, the API could remain the same and added processing could occur "behind the scenes".

There are a few other justifications for changing an API, but in general, I believe that APIs should be backwards compatible.