API Versioning

Our Approach

We use API versioning to indicate changes to our APIs. If there are changes to the behavior of an API, or to its request parameters or responses, we will make a major, minor or patch version increase depending on the scope of the change.

Backwards Compatibility

In the case of minor or patch version increases, backwards compatibility will always be maintained. In the case of major version increases, the new version will not be backward compatible. In such cases, we will announce the version increase in advance, and maintain the previous version for a period of time to allow for API users to make the requisite updates.

Examples of Major Changes (v1.4.7 > v2.0.0)

• URL path changes
• Authentication changes
• Any other change that will not work with previously supported requests

Examples of Minor Changes (v1.4.7 > v1.5.0)

• Adding new endpoints
• Adding new endpoint paths
• Adding new attributes to the JSON response

Examples of Patch Changes (v1.4.7 > v1.4.8)

• Changing the order in which attributes are presented in the response
• Changing a required payload attribute to optional