“Public APIs are forever: Only one chance to get it right”?

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?

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.

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…

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.

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.

Breaking changes must be avoided at all cost, except if there is a VERY good reason for it.

Every time you introduce a breaking change it will exponentially ripple to all dependent software.

Much of that software is vintage, complex, maintained with constrained resources, or made on spare time. Still it is quite useful.

It may easily be destroyed by such change.

A better option is to extent the functionality, or to differentiate what code is just for retro-compatibility.

It is true to in the sense that if you don’t want to cause working software to stop working, then you should keep public API’s around forever. You can introduce new API’s, but you can’t remove older APIs.

But there is no certainly no guarantee that any public API will be kept around forever. Public API’s are broken or removed all the time for various reasons. For the owner of the API, it is typically a cost-benefit analysis. Maintaining compatibility with an old API might prevent improving the underlying platform or require complex compatibility layers.

Microsoft have a reputation for going to great lengths to maintain compatibility, because they know the reason people use Windows is the available software. Apple, for better or worse, tend to have a larger tolerance to breaking applications.

In theory you can “deprecate” old API’s, but this does not automatically mean software relying on the old API will be updated. If the software breaks in a later OS update, the user will still blame the OS.

Of course there are plenty of examples of vendors removing public API’s and just accepting the inevitable uproar. When it comes down to it, it is a business decision rather then a technical decision.

Changing a widely used API is a pain. You need a very good reason.

Many languages allow you to mark things as “deprecated”. So the first step is to provide a better API, mark the old one as deprecated, and giving instructions how to change it. Any decent developer will make changes at that stage, bit by bit.

Many languages allow removing the implementation in a new library version. At that point developers either change or stay stuck with the old library version. At this point any reasonable developer will change all calls.

And the final step is removing the old API.

Filed under: softwareengineering - @ 18:51

Thẻ: android, api, api-design

Thiết kế website giá rẻ

Danh mục

“Public APIs are forever: Only one chance to get it right”?

If you program, you are an API designer

Useful modules tend to get reused

Thinking in terms of APIs improves code quality

API design is a noble and rewarding craft