API Versioning

All API URLs MUST include only the “major” portion of the API version. Registration of APIs and their versions MUST be done through the Developer Console.

Incrementing the major version number in the URL is mostly synonymous with a change that alters the contract of the API which breaks backward compatibility with the current version (a “breaking change”) or a significant change in the operation of the API itself.

Examples where the version number MUST be incremented include:

• Existing fields renamed or removed from the request payload
• Existing fields renamed or removed from the response payload
• New required fields added to the request payload
• Fields that were optional become required
• Data type changes in the request and/or response payload (e.g. integer to float)
• Underlying algorithmic or other functional changes that result in appreciable difference(s) in the values returned by the new version (for example, a score on a 0-10 scale changed to a 0-100 scale, the total charges now include shipping, or the violation count now includes warnings)

Examples where the version number would not increment:

• New optional fields added to the request payload (as long as there is no change in the API results if those fields are not included)
• New fields added to the response payload
• Code changes to the API service that do not modify the content of the response or change any key algorithmic functionality impactfully.