How We Version

Sparta introduces new changes to the API in 3 ways depending on the changes being implemented:

• current version implementation
• a minor version release
• a major version release

When we release a new API version, you can choose to upgrade to gain access to new features. When changes are implemented into the current API version, these features will become available to customers using this version, without needing an upgrade.

The most recent product improvements will be included in the latest version of the API. We recommend upgrading to the latest version in order to take advantage of new functionality and optimise for the best user experience.

Note: A publicly released version of an Sparta API will never change in any way that could impact your integration.

Current version implementation

Sparta will implement changes into current API versions, without a new version release, when the changes being introduced will not interfere with your integration. These changes represent independent features which do not alter pre-existing logic. For example:

• adding new API endpoints
• adding optional request parameters to existing API endpoints
• reordering properties returned from existing API endpoints

In this case, you can use these changes immediately without having to upgrade API version (if you are currently on the API version in which the changes were introduced).

Minor Releases

Sparta will release a minor API version when the changes being introduced are considered backwards compatible, i.e. additive changes. For example:

• adding new properties to the responses from existing API endpoints
• altering the message attributes returned by validation failures or other errors
• adding new values to existing properties in responses from existing API endpoints

In this case, you can use these changes immediately without having to upgrade API version (if you are currently on the API version in which the changes were introduced).

Major Releases

Sparta will release a major API version if any of the changes being introduced are backwards incompatible. In this case, if you would like to move to a new major version you will likely need to update your integration.

Major versions are released less frequently. An example of a major release would be v2.

Sparta considers the following changes to be backwards incompatible:

• removing a feature of the API
• removing or renaming a resource, field, method or an enum value
• changing the type of a field (eg. integer becomes string or float)
• changing the URL format
• adding a new or modifying an existing validation to an existing resource
• changing existing error response codes/messages
• changing authentication mechanism
• changing the length of strings (eg. max_length changing from 100 to 255)
• changing the meaning of a field even if the type is unchanged

Support Timelines and Deprecation

All of our API versions are released with an indefinite support timeline until a deprecation notice is issued. Deprecation notices will give you at least 12 months to migrate to a newer API version.

Deprecation notices will contain:

• WHAT is being deprecated: an entire version (such as v3), set of versions (such as v3—v4) or particular functionality (such as ping endpoint across v2-3)
• WHEN it’ll come in effect: a clear timeline, allowing minimum 12 months to migrate
• HOW it’ll impact you: an outline of clear consequences for deprecation, which could be one of:
  • a complete removal of functionality
  • functionality available, but without product support or updated documentation
• a MIGRATION GUIDE outlining steps to achieve the functionality in a new way

Deprecation notices will be available:

• as an email to clients impacted by it (with reminders every 90 days)
• as a notice next to relevant functionality on this website
• as a header on API responses when clients make an API call to affected endpoint