Atlassian REST API policy

Compatibility policy

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.

Backwards compatibility

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.

Stable URIs

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.

Stable representations

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.

Plugin extensions

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.

API versioning

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/hal+json or application/hal2+json as appropriate.

Forward compatibility

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.

Postel's Law

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.

Deprecation policy

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.

Announcements

All effort should be taken to notify consumers, through all relevant communication channels of new deprecations.

Time frames

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, with these exceptions:

• Modifications to the API are necessary to mitigate critical security vulnerabilities, critical reliability issues, or data integrity issues.
• Where APIs are provided by plugin extensions as noted above.

Detectability

Requests which are made to deprecated APIs SHOULD return a header on the response to notify the consumer that the endpoint is deprecated.