API Stability

Apache NetBeans Wiki Index

Note: These pages are being reviewed.

In order to clearly communicate what stage an API is in, whether it is still being evolved, whether it is expected to ever be real API or whether it is stable and ready to use, let us introduce a system of stability clasification for APIs. The aim is to give the code authors way how to communicate their intention with particular feature and others to find out such information.


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 is risky and should be avoided.


Friend API is used for features accessible to specific components in the system, that help to overcome the lack of a real stable API, but are 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 to try 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. The "forever" and "never" should not be taken as absolute: It is possible to change the contract, but only in major versions and only after a careful considerations and in cases where it is imperative that a change be made. Stable contracts should preserve the investments of those entering into them (users of an API).


Official are stable ones and also packaged into one of NetBeans official namespaces: org.netbeans.api or org.netbeans.spi or org.openide. By packaging a contract into this package (and making it part of a release) one notifies others that the contract is stable - with all the consequence (except the conditional support for early adoptions - such modules has code base name that ends with with /0). Also, the impact of possible incompatible changes to official API should be minimized by providing compatibility bridges and keeping binary compatibility even when source one is droped (see the preservation section).

Third Party

Third party interfaces are provided by other parties that do not follow the NetBeans rules and thus are hard to classify. It is prefered not to expose such interfaces as part of own contracts, in order to insulate users of NetBeans APIs from unexpected changes made in the imported interfaces.


Standard is similar to the third party classification. Also provided by someone out of NetBeans, but by someone expected to evolve the interface in compatible way (for example JSRs). The standard is expected to not change frequently.


Deprecated. After a while, nearly every API, regardless of what state it is, becomes obsoleted. 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 deprecated shall be supported for reasonable amount of time (a release) 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 (e. g. autoupdate centers).