Versioning

To support the ongoing development of the API whilst ensuring that existing clients have sufficient time to take advantage of improvements or make necessary changes, the API is versioned using a semantic versioning approach (see http://semver.org for background information). The version is specified as part of the URL used for API calls. For example:

https://api.englishlanguageitutoring.com/v2.3.0/account/YOUR_ACCOUNT_ID/text/1234/results

The version string takes the form vX.Y.Z where X is the major number, Y is the minor number and Z is the patch number. API versions with the same major number are compatible.

At any time, the latest and immediately previous major versions of the API will be available for use. For example, if the latest API version is v4.Y.Z, version v3.Y.Z will still be available.

Compatibility

Semantic versioning enables the introduction of changes in a controlled way and makes it clear whether changes are designed to be backwards compatible (meaning API client code changes should not be necessary when upgrading the API version being called), or whether changes break backwards compatibility (breaking changes mean API client code must be changed when upgrading the API version being called). However, it is possible to envisage that a particular change to the API could be classed as either a backwards-compatible change or a breaking change from the point of view of an API client, depending on the details of how the client is implemented. For greater clarity, various possible changes are outlined here and grouped into backwards-compatible or breaking changes.

Backwards-compatible changes

These would result in a new minor API release.

• Addition of a new API endpoint
• Addition of an optional attribute in a JSON request body
• Addition of further possible string values for an attribute in a JSON response body
• Addition of an attribute in a JSON response body

Breaking changes

These would result in a new major API release.

• Removal of an API endpoint
• Addition of a required attribute in a JSON request body
• Removal of a non-optional attribute in a JSON response body
• A change to the type or format of a value in a JSON request or response body
• A change to the semantics of a value in a JSON response body, for example, if the CEFR score range changes from 0.0-13.0 to 0.0-25.0

Discovering supported versions

A versions endpoint is provided to enable programmatic determination of available versions. Unlike the other API endpoints, the versions endpoint does not need a version specified as part of the URL.

Request

Method and URI:

GET /account/ACCOUNT_ID/versions

Request parameters:

Response

HTTP status code: 200

Response body JSON:

{"type": "success", "code": 200, "versions": ["0.1.0", "0.2.0", "0.3.0", "1.0.0", "2.0.0", "2.1.0"]}