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.

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?

share|improve this question
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 '13 at 7:30
18  
@tp1: writing perfect code is a skill that does not exist in the real world. –  Michael Borgwardt Feb 23 '13 at 16:16
3  
@michael borgwardt: Just need to choose which version of perfect to use. –  tp1 Feb 23 '13 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. –  Josh Petitt Feb 24 '13 at 3:07

8 Answers 8

up vote 32 down vote accepted

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.

share|improve this answer
2  
"both a difficult technical problem and a difficult technical problem" You repeated "technical" twice. –  luiscubal Feb 23 '13 at 13:08
12  
@luiscubal: that's because it's a damn difficult technical problem indeed. –  Michael Borgwardt Feb 23 '13 at 21:23
3  
@luiscubal You mean once. Repeated once, said twice. –  Joe Z. Feb 25 '13 at 13:40
4  
"Public Answers aren't forever..." –  Chris Feb 25 '13 at 19:32
2  
@Chris Not really. Justin's answer is now no longer compatible with luiscubal's comment. :-) –  svick Feb 28 '13 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...
share|improve this answer
1  
Technically diamond is metastable. Thermodynamically speaking, graphite is a more stable form of carbon. –  detly Feb 25 '13 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.

share|improve this answer
    
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 '13 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.

share|improve this answer

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.

share|improve this answer

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.

share|improve this answer

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!! :)

share|improve this answer

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.

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.