API Versioning

All API URLs MUST include only the “major” portion of the API version.

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.