API Versioning

Semantic Versioning

The API specification is versioned with Semantic Versioning. In general, changes to the major or minor version number indicate a change to the API itself, while a change to the patch number indicates a change to the specification that does not change the semantics of the API (eg a spelling change in a description of a parameter).

We consider a breaking change to be anything which would break a client’s use of existing parts of the API, but not anything which extends the API without affecting a client’s use of existing parts. Especially, we do not consider the following to be breaking changes by themselves (however, they would be breaking if they affected the semantics of existing parts of the API): new optional parameters, new allowed values for parameters, new allowed values for enumerated result types, new optional JSON fields in input, and new JSON fields in results. Therefore a client should not do strict validation of results or otherwise make assumptions about JSON fields it does not access.

Examples

The following are breaking changes (would be a major version change):

• Changing the path for an API call.
• Adding or renaming an API call, required parameter, or JSON field in input.
• Changing the type of a parameter or JSON field in input.
• Changing the meaning of an existing parameter or JSON field.

The following are non-breaking changes (would be a minor version change):

• Adding a new API call.
• Adding a new optional parameter to an existing API call.
• Adding a new value to an input enum (eg report type).
• Adding a new optional field to a JSON object in input.
• Adding a new field to a JSON object in a response.

The following are patch changes (would be a patch number change):

• Changing the description of any part of the API in a way which does not affect semantics.