Versioning

Overview

The major version, the v1 in the URLs is fixed and a way for us to namespace radically different API suites, for example, a new GraphQL set of APIs could be v2. The individual operations may evolve over time and breaking changes are introduced with a version bump to that operation.

When registering a new client application the default version to be used is selected and all API operations will adhere to that version unless a different specific version is requested via content negotiation. In this way client applications can rely on a stable interface. The default version can be changed on your client if neccessary after it has been updated.

If there is no default version configured for the client, or for requests without a client, then the latest stable version will be assumed. The latest stable version is documented in the Changelog. To avoid unexpected breaking changes it is not recommended to rely on the latest version in production code.

Policy

A new version of an operation is only introduced when there are breaking changes to that operation.

A breaking change is defined as:

• A property of the operation payload or response is removed or relocated.
• The JSON data type of an operation payload or response changes, for example from string to number.
• A property of the operation payload or response becomes or ceases to be “nullable” - whether or not JSON null is a valid value for the property.
• A new mandatory query parameter is introduced.
• A new mandatory payload property is introduced.

We do not create a new version if there are new optional parameters or keys in the request body, or extra keys in the response, we expect existing clients to ignore them.

Deprecation and removal

Old and new operations will be supported in parallel for an appropriate time period before discontinuing old ones.

Where a version of an operation is to be deprecated, announcements will be made to consumers along with a warning header: ‘Warning: 299 - deprecated API version’ in the HTTP response. Advanced notice of at least 6 months will be given before support ends.

Specific versions via content negotiation

In cases where the client application needs to use a version of an operation that is different to its registered default - content negotiation via the Accept header can be used to request a specific version of the operation. This can be useful if the client application wants to migrate to a new version of a particular operation but continue to use its default version for the rest of its operations. It can also be useful if you are upgrading your client to a new default version gradually and without downtime.

We use vendor specific MIME types to specify versions in headers, for example, if the client application has default version 1.1 but would like to GET applications in a newer 1.2 format the Accept header would be application/vnd.wcn.v1.2+json for all other operations the normal MIME type application/json should be used and the default version will be used.