Versioning for the EMS API

The EMS API supports versioning of Resources. This can be for:

• The Resource received in the Response (Response versioning)
• The Resource sent in the Request (Request versioning)

Versioning has been implemented in the API so that breaking changes to the format of a Resource will not affect existing clients because a compatible version will still be maintained. All API calls require a version to be specified for both the Request and Response, meaning that all API calls are tied to a particular version.

Response Version

The Response version is specified in the Accept field of the request headers.

Accept: {Content Type};version={Version}

Where {Content Type} is described here and {Version} is the integer version number for the Resource in the Response.

The applicable Response versions are described in the API call documentation (as a 'V{n}' prefix next to the Resource name, where {n} is the version number).

If the version is set incorrectly or is not included, the API will respond with a HTTP 400 (Bad Request) status code and will not execute the request.
If the version number does not exist for the Resource, the API will respond with a HTTP 404 (Not Found) status code and will not execute the request.

Request Version

The Request version is only relevant for API calls where a resource is sent to the API (i.e. PUT or POST requests). The version is specified in the Content-Type field of the request headers.

Content-Type: {Content Type};version={Version}

Where {Content Type} is the MIME type of the body of the request, as described in the API call documentation and {Version} is the integer version number for the Resource in the Request.

All PUT or POST requests should currently be made with {Version} set to 1.

If the version is set incorrectly or is not included (PUT or POST requests only), the API will respond with a HTTP 400 (Bad Request) status code and will not execute the request.