Question

I’m working now on an API for developers feature of our product.

The first version was released and it has small number of users at the moment. Since I started to develop its second version, some parts were reworked, some parts were removed to make the API more elegant and clear.

But the 2nd version deployment can be a pain for old version users. Our marketing department is planning to enhance our API product a lot, add more features to it.

How should I build the system, so
1) we wouldn’t be constrained to the ‘old version’ to add new interesting features
2) current API users won’t be dissatisfied because of the need to rework their systems in order to comply with the changed API

Or should the API products be tested in a sandbox for quite a long period of time before the public release, so there wouldn’t be any significant modifications in the specification?

Answer 1

When you have to make changes to the API which already has some users, probably the best route is to deprecate the old API calls and encourage use of the new calls.

Removing the capability of the old API calls would probably break the functionality of old code, so that is probably going to cause some developers using your ‘old’ API to become somewhat dissatisfied.

If your language provides ways to indicate that certain functionality has been deprecated, it can serve as a indication for the users to stop using old API calls and transition to new calls instead. In Java, the @deprecated javadoc tag can provide notes in the documentation that a feature has been deprecated, or from Java 5 the @Deprecated annotation can be used to raise compile-time warnings on calls to deprecated APIs features.

Also, it would probably be a good idea to provide some tips and hints on migrating from the old API to the new API to encourage people to use the new way of interacting with the API. Having examples and sample code on what to do and what not to do, the users of the API would be able to write code according to the new, preferred way.

It’s going to be difficult to change a public API, but with some care taken in the transition from the old to new, I believe that it the amount of pain inflicted on the users of the API can be mitigated to a certain extent.

Here’s an article on How and When to Deprecate APIs from Sun, which might provide some more information on when it would be appropriate to deprecate parts of APIs.

Also, thank you to David Schmitt who added that the Obsolete attribute in .NET is similar to the @Deprecated annotation in Java. (Unfortunately the edit was overwritten by my edit, as we were both editing this answer at the same time.)