Skip to content

Life Cycle of an API

August 5, 2009
An API can be evolved
Spontaneously – someone is developing a feature, and another person finds it useful and starts to use it. Later they find out about each other, share their experiences and very likely find that the original design of the feature is not general enough or that it was never intended to be treated as an API In order to evolve it toward being an API they discuss changes to make the feature better and after few iterations it can become a useful and stable contract.
By design – there is a known need for a contract between two components of the system. The requirements are collected, the problem area investigated, the use cases understood, and then someone designs and writes the API. Now others can use it in real world, comment, file bugs and enhancements which results in improvements to the API and finally evolve it into a state where it is a useful and stable contract.
Private is a category for features that are accessible but are not intended for use outside of their component (module). Such features are subject to change with every release and depending on them are risky and should be avoided.
Friend API is used for features accessible to specific components in the system that helps to overcome the lack of a real stable API, but is intended only for use between these friend components and nobody else. Often friend components are developed by the same group of people. A change to this contract can be done every release, but owners of those friend components must be notified in advance. No one else should depend on such features – the author of this API does not have the intent to create a general purpose API.
Under development is a name for a contract that is expected to become a stable API, but that has not yet been finished. The current state serves as a proof of concept, and others are encourage trying it and comment on a dedicated mailing list. Incompatible changes may be done between releases, but should be rare, not radical and properly announced on the mailing list.
Stable interfaces are those that have received a final state and the maintainers are ready to support it forever and never change them incompatibly. It is possible to change the contract, but only in major versions and only after careful considerations and in cases where it is very important that a change be made.
Third party interfaces are provided by other parties that do not follow the rules and thus are hard to classify.
Standard is similar to the third party classification. Also provided by someone, but by someone expected to evolve the interface in compatible way the standard is expected to not change frequently.
Deprecated. After a while, nearly every API, regardless of what state it is, becomes outdated. Usually a new, better support for the same task has been developed which replaces the old API. In such case, mark the old API deprecated. A previously stable API that changed its stability to deprecate shall be supported for reasonable amount of time to communicate to users that they shall migrate from it to the new replacement. After that time the API can be removed from the product, while trying to preserve it for old clients by making it available in alternative ways
No comments yet

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Google+ photo

You are commenting using your Google+ account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )


Connecting to %s

%d bloggers like this: