In an OS book I just read that, "Public APIs are forever: Only one chance to get it right". Is it true? Is it applicable only in APIs of Operating Systems or other APIs too? For example, will this be true for the APIs of Android Applications such as Tasker, Locale and Pushover?

  • 2
    I would extend the principle to all code. There just isn't enough time to write the same thing multiple times. Writing perfect code is a skill that can be learned.
    – tp1
    Feb 23, 2013 at 7:30
  • 22
    @tp1: writing perfect code is a skill that does not exist in the real world. Feb 23, 2013 at 16:16
  • 4
    @michael borgwardt: Just need to choose which version of perfect to use.
    – tp1
    Feb 23, 2013 at 16:29
  • 1
    I've seen this in the real world, and it depends on what type of API. Lesson learned: the first requirement in any "public facing" web API is the ability for the API user to select which version of the API they will use. Feb 24, 2013 at 3:07

8 Answers 8


It is generally true for any public API, yes. Once you expose an API to the public and people start to build applications that depend on that API, it becomes extremely difficult to change the API because doing so will break all those applications. That tends to be both a difficult technical problem and a difficult political problem.

Of course, it is possible to change a public API. It does happen, for example, that projects will depricate an API in one release, introduce a new API, and then remove the old API in some future release. But that assumes that every (important) application that uses the old API will be rewritten to use the new API before the old API is removed. That often takes multiple years. And that means that the owner of the public API is imposing a cost on every other project that consumes the API. Since there are generally far more consumers of an API, those consumers tend to be a relatively powerful political lobby.

  • 2
    "both a difficult technical problem and a difficult technical problem" You repeated "technical" twice.
    – luiscubal
    Feb 23, 2013 at 13:08
  • 12
    @luiscubal: that's because it's a damn difficult technical problem indeed. Feb 23, 2013 at 21:23
  • 3
    @luiscubal You mean once. Repeated once, said twice.
    – Joe Z.
    Feb 25, 2013 at 13:40
  • 4
    "Public Answers aren't forever..."
    – CLo
    Feb 25, 2013 at 19:32
  • 3
    @Chris Not really. Justin's answer is now no longer compatible with luiscubal's comment. :-)
    – svick
    Feb 28, 2013 at 22:06

Quote author is Joshua Bloch, the statement is from his Bumper-Sticker API Design article:

Public APIs, like diamonds, are forever. You have one chance to get it right so give it your best.

For more details on that, author refers readers to his conference session presentation, "How to Design a Good API and Why it Matters". Slide Why is API Design Important to You states it pretty clearly that this is relevant to any programming activity (operating systems or not, doesn't matter to author):

  • If you program, you are an API designer

    • Good code is modular - each module has an API
  • Useful modules tend to get reused

    • Once module has users, can’t change API at will
    • Good reusable modules are corporate assets
  • Thinking in terms of APIs improves code quality

Slide Conclusion also stresses this as a general approach:

  • API design is a noble and rewarding craft

    • Improves the lot of programmers, end-users, companies...
  • 2
    Technically diamond is metastable. Thermodynamically speaking, graphite is a more stable form of carbon.
    – detly
    Feb 25, 2013 at 3:51

APIs always change, otherwise what would be the point of system upgrade? Changing internals only?

Each version of system brings new APIs, old APIs become obsolete and obsolete APIs disappear.

API change only has to be very careful both technically and in terms of communication.

  • As long as you can commuincate well with all your consumers and they can talk t their users - look at Windows: Windows has tons of old, deprecated, bad APIs as end users like running extremely old applications even on modern systems
    – johannes
    Feb 24, 2013 at 1:28

My opinion would be that once released, that 'version' of the API is forever, but you can deprecate it by releasing a '2.0' API (there are several examples where this is happening - currently, I can think of Strava who have released a 2.0 version of an API for development against to consume their services).

The problem is supporting that original API ad infinitum... I guess it depends on the usage of the old API, and what the value of those API consumers hold to you.

Going back to 'the old days' of say Windows 3.x and 9x etc., once release, those OS APIs were done and set. Now, OS updates are pushed all the time, so new APIs can be released, but I think so long as you are running a particular OS flavor (major release), those APIs would only be added to, never removed... may not be the case for the 'next' major release though.

Hmm, maybe I strayed from the original question intent.


It depends on what kind of API it is (and I am assuming breaking changes, otherwise the statement is obviously not true).

If the caller can choose what version they're using (e.g. with libraries/frameworks that are bundled with the calling application), then changing the API is not a huge problem - but still bad for the reputation of the software. People like to to upgrade seamlessly.

On the other hand, when people cannot keep using the old version of the API (such as with an online service, or things like a browser or OS where running old versions is very undesirable), then changing APIs in an incompatible way is very bad indeed, since it will break all software that uses it and is not updated as well. This imposes a maintenance cost on developers, and they'll hate you for it. And software that isn't maintained and breaks will reflect badly on you as well.

On the gripping hand, there is at least one API provider who constantly introduces breaking changes in the API and is ridiculously successful anyway: Facebook. But they do manage the changes very carefully: there is a published policy, breaking changes are announced and explained at least 90 days beforehand, and developers can choose to activate them early within that timeframe.


If you have the foresight to include a version number in the API itself. Either on the connection/initialisation call, or, somewhere near the beginning of the parameter list on each call, then your API can evolve and mutate over time without disrupting existing clients.


Although all what we do is to make 'em best at one go, but since time change and improvement comes, sometimes we need to update the information, as many of giant providors have been doing, (like face book several update, twitter one major turning to oAuth and several major, but at most possible all comes with improvement so no frequent changes. And Yes please don't stop supporting older one, It hurts!! :)


Anytime that you release any sort of communications protocol, which would obviously include an API, you have one chance to get it right in the sense that the protocol/interface must be backwards-compatible and extensible.

This allows you to add new functionality and release new versions without having to worry about breaking people who are using older versions. Never in the software world are you going to have a situation where you can just have a hard cutover at a certain point in time, and everyone drops the old version and starts using the new version.

Your Answer

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