This page outlines Atlassian's REST API policy. Click the links below to skip ahead to sections.
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:
- The meaning of HTTP response codes can be trusted. If a URI that used to 200 now returns a 404, you know it is because the resource cannot be found, not because the resource has moved to another location
- A resource MAY support additional query parameters in future versions but they WILL NOT be mandatory. The absence of a value or a default value (as appropriate) will maintain prior behaviour
- If a resource accepts a representation (e.g. via POST or PUT), it will continue to accept the same representation in future versions. Any additional properties that are recognised in a resource WILL NOT be mandatory, and the default value assumed in their absence will be chosen to maintain the previous meaning of the resource
- A resource MAY be modified to return a "redirection" response code (e.g. 301, 302) instead of directly returning the resource. Clients MUST handle HTTP-level redirects, and respect HTTP headers (e.g. Location)
- The canonical URI of a resource used in "self links" or used by other resources to point to the resource MAY change
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.
Structured representations (application/json)
Resources with a media type of
application/json 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:
- If a property has a primitive type and the API documentation does not explicitly limit its possible values, clients MUST NOT assume the values are constrained to a particular set of possible responses
- If a property of an object is not explicitly declared as mandatory in the API, clients MUST NOT assume it will be present
- New properties MAY be added to a representation at any time, but a new property MUST NOT alter the meaning of an existing property
- If a property of an object is a URI, then the resource identified by that URI MUST maintain the same compatibility guarantee
Resource/rate limits and paging
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 Content-Type header
application/hal2+json 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.
- Request query parameters that are not recognised by the server will be ignored
- Expansion parameters that are not recognised by the server will be ignored
- Properties of structured (i.e. JSON) data submitted via mutative requests that are not recognised by the server will be ignored
- Data that is intended to be passed to a plugin extension that is not installed or is not active will be ignored
The REST API deprecation policy should be consumed in additional 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 it's 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.