Versioning

Approach

A new version of the API is created only when a breaking change is made to the API.

Breaking changes include:

  • removing / renaming endpoints
  • removing / renaming response data (i.e body properties, headers)
  • adding required input parameters to requests (i.e. query string parameters, body properties, headers)
  • changing the error code for an error (from one specific code to another)

Non-breaking changes include:

  • adding endpoints
  • adding response data
  • adding optional input parameters to requests
  • removing input parameters from requests
  • marking items as deprecated
  • changing the error code for an error (from a generic error code to a specific one)

In general, IRIS tries to keep new API versions to a minimum, instead favouring the use of non-breaking changes to evolve API endpoints.

However, every effort is made not to disrupt the overall design of the API, and to keep it lean and easy for developers to understand.

Version numbers

Changes to the API are deployed to production as part of a GXP release - these generally happen every couple of weeks, and have sequential 4.x version numbers (e.g. 4.0, 4.1, 4.2 etc.).

The API version uses the version number of the GXP release, with a 'v' prefix added and the decimal point removed. For example:

GXP release version API version
4.0 v40
4.1 v40
4.9 v49
4.10 v49
4.11 v411

Because not every GXP release involves breaking changes to the API, the list of API versions will form an irregular sequence (e.g. v40, v49, v411).

Version numbers will be shown in endpoint URLs, in the following format: https://api.iris.net/api/v40/System/Session/Initialise

Backwards Compatibility

Atlassian defines backwards compatibility thus:

'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.'

For a given v4 API endpoint, we guarantee backwards compatibility between two successive API versions, as long as no breaking change has been made to that endpoint.

In other words, non-breaking changes to an endpoint will not affect its backwards compatibility (but breaking changes will).

Deprecated items

The following may be marked as deprecated:

  • endpoints
  • request querystring parameters, body properties
  • response body properties

Deprecation serves as a warning that an item is likely to be removed in the subsequent API version.

Retiring API versions

We retire an old API version when it is no longer in widespread use; we aim to give developers three months' notice of this.

Testing

We continually test all live (i.e. non-retired) versions of the v4 API; a comprehensive suite of integration tests is run as part of the GXP platform's Continuous Integration pipeline.

When we create a new API version, we copy the integration tests from the previous version, and amend them to cover the changes in the new version.