Beyond Software Architecture[c] Creating and Sustaining Winning Solutions

Earlier in this chapter I noted that publishing an API, or any other technique for extending and integrating your system, is an important public commitment to the people relying on it. The level of commitment to an external API for customers is very different from that developers may have to an API they are creating for other members of the development team. It is relatively easy to negotiate changes to an API within a teamhealthy teams do this frequently during development. However, it is very difficult to negotiate changes to an external, published API, especially when hundreds or thousands of customers have created applications that rely on it. I've read how Web services will change all of this, but I don't believe it. An external, published API represents a serious commitment to your customers. You can't change it on a whim.

Like other aspects of your system, however, the techniques you use to provide extension and integration, including APIs, will change over time. Early versions of the system may not expose the right kinds of services or may not expose the right services using the proper underlying technology. The trick is to carefully manage the evolution of APIs so that the customers relying on this integration/extension technique will have time to plan for and accommodate any changes.

Techniques

Here are some approaches to consider in managing APIs.

Give Plenty of Warning

Customers should know about extension and integration changes as soon as possible. A good rule of thumb is to announce changes planned for release n ₊₁ in release n. To help in the transition from the old to the new API, provide tools to identify the old ones and, when possible, automatically convert the old ones to new ones.

Provide One Release of Overlap

Once the new APIs are released in version n, the old APIs should not be fully deprecated until release n ₊₁ . In other words, an API must be removed in no less than two full releases of the product.

Provide Backward Compatibility Layers

Once the API is no longer officially supported you may find it helpful to offer an "unsupported" backward compatibility API (or layer), provided that the underlying functionality of the product hasn't changed. This API is often implemented as an optional module that can be installed as needed by users. Be careful with this approach, as it may create a false sense of security among your users that portions of the API will always be there.

Provide Automated Tools That Identify or Convert Calls To Deprecated APIs

Provide tools that can automatically identify and/or convert calls to deprecated APIs and convert them to the new platform. These tools benefit your application by making it that much easier to move to the upgraded version.