Wherever possible, REST resources and their representations will be maintained in a backwards compatible manner.
If it is necessary to change a representation in a way that is not backwards compatible, a new resource (or media type) will be created using the new representation, and the old resource (or media type) will be maintained in accordance with the deprecation policy, attached at the end of this document.
The behaviour of an API may change without warning if the existing behaviour is incorrect or constitutes a security vulnerability.
An API is Backwards Compatible if a program written against one version of that API will continue to work the same way, without modification, against future versions of the API.
If a resource exists at a particular URI, that same resource will continue to exist with the same meaning in future versions. This means:
If the resource at a URI is documented as being available in a specific media type (e.g. via the Content-Type header), that media type will be maintained. If a resource returns a default media type in the absence of content negotiation, that default will be maintained.
Resources with a media type of have additional stability guarantees.
If a property exists in a JSON object returned by the REST API, it will continue to be returned with the same name, and the same value type (i.e. String, number, array or object). If that value is an array, the type of the contents of the array will not change. If the value is an object, that object will satisfy the same compatibility guarantees as the document as a whole:
Resource and rate limits, and the default and maximum sizes of paged data ARE NOT considered part of the API and may change (possibly dynamically). It is the responsibility of the client to read the road signs and obey the speed limit.
Certain parts of the API are able to be extended by plugins. Plugins that extend the API MUST follow the compatibility guidelines. However, since plugins may be enabled, disabled, upgraded or downgraded at any time without warning, clients MUST NOT assume that data provided by extensions will be present in a response, or that extension data provided in a mutating request will necessarily be saved.
Responses will not be tagged with the version of the API. While a version number for the API may be available from certain resources (server info, plugin status, etc) clients should be aware that the deployed API version might change without notice, even between requests. The recommended way for a client to proactively determine if a particular capability is available in the API is to request it and see if it is there, and handle failure gracefully if that capability becomes unavailable during an interaction.
Media types MAY be used to indicate forms of representation of a resource that have changed over time, particularly when underlying formats have changed. For example, if the HAL specification were to hypothetically have multiple versions, we could differentiate the responses on a single resource using the header or as appropriate.
An API is Forwards Compatible if a program written against one version of the API will also work the same way, without modification, against previous versions of the API.
We make no guarantee of Forwards Compatibility in our REST APIs, but we provide the following non-normative guidelines about our approach to forwards compatibility.
Be conservative in what you do, be liberal in what you accept from others
Where possible, we follow the Robustness Principle above. This means that the API will determine what to do with a request based only on the parts of that it recognises.
The REST API deprecation policy should be consumed in addition to any other relevant deprecation policies. When there is a conflict of policy, the most restrictive policy should be followed.
All effort should be taken to notify consumers, through all relevant communication channels of new deprecations.
Publicly accessibly REST APIs must be given reasonable notice of deprecations. Any deprecated REST API in the cloud environment MUST be available in its original form for at least 6 months, UNLESS there are critical security vulnerabilities or these APIs are provided by plugin extensions as noted above.
Requests which are made to deprecated APIs SHOULD return a header on the response to notify the consumer that the endpoint is deprecated.