Autodata REST API 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.
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 a future version 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. 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)
Versioned 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 ensure this can be managed.
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. Where possible, we follow the Robustness Principle. 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.
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.
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 MUST be available in its original form for at least 6 months, UNLESS there are critical security vulnerabilities.
Requests which are made to deprecated APIs SHOULD return a header on the response to notify the consumer that the endpoint is deprecated.