All APIs evolve as bugs are fixed, new features added and features are removed
The goals of XenAPI evolution are:
In this document, the term XenAPI refers to the XMLRPC-derived wire protocol used by xapi. The XenAPI has objects which each have fields and messages. The XenAPI is described in detail elsewhere.
Each element of the XenAPI (objects, messages and fields) follows the lifecycle diagram above (inspired by symbian ). When an element is newly created and being still in development, it is in the Prototype state. Elements in this state may be stubs: the interface is there and can be used by clients for prototyping their new features, but the actual implementation is not yet ready.
When the element subsequently becomes ready for use (the stub is replaced by a real implementation), it transitions to the Published state. This is the only state in which the object, message or field should be used. From this point onwards, the element needs to have clearly defined semantics that are available for reference in the XenAPI documentation.
If the XenAPI element becomes Deprecated, it will still function as it did before, but its use is discouraged. The final stage of the lifecycle is the Removed state, in which the element is not available anymore.
The numbered state changes in the diagram have the following meaning:
Each lifecycle transition must be accompanied by an explanation describing the change and the reason for the change. This message should be enough to understand the semantics of the XenAPI element after the change, and in the case of backwards-incompatible changes or deprecation, it should give directions about how to modify a client to deal with the change (for example, how to avoid using the deprecated field or message).
Every release must be accompanied by release notes listing all objects, fields and messages that are newly prototyped, published, extended, changed, deprecated or removed in the release. Each item should have an explanation as implied above, documenting the new or changed XenAPI element. The release notes for every release shall be prominently displayed in the XenAPI HTML documentation.
The XenAPI documentation will contain its complete lifecycle history for each XenAPI element. Only the elements described in the documentation are “official” and supported.
Each object, message and field in
datamodel.ml will have lifecycle
metadata attached to it, which is a list of transitions (transition type *
release * explanation string) as described above. Release notes are automatically generated from this data.