Versioning is an essential component of API design. It enables Speed to improve API without disrupting your applications when new updates are released. These updates are almost always backward compatible; however, there may be a few backward-incompatible changes. To keep existing functionality in your app after a backward-incompatible change, you must change the code. Backward compatible changes will be additive and rolled out to the most recent version when ready, requiring no developer work unless you want to use the new functionality.
One can then continue to use the old API version, or upgrade to the new Speed platform API version. Speed, as previously stated, implements rolling versions, which are identified with the date they were released current version: 2022-04-15. When you make your first API request, your account is automatically pinned to the most recent version available, and any subsequent API calls are implicitly assigned to that version. This approach eliminates the need for you to include versioning information in the URI, query parameters, or custom headers.
A new application is backward compatible when it supports the features of the older versions. We consider the following changes to be backward compatible:
- Addition of a new endpoint
- Addition of a new optional parameter
- Addition of a new response field
- Changing text in error messages
- Adding new enum values.
- Changing the length or content of any API identifier
A major dated version will be released when a backward-incompatible change is introduced in the API. We will publish migration guides when launching a new major version to assist developers in migrating over to the new version. The following are the main principles of our versioning strategy:
The following are the main principles of our versioning strategy:
- All backward-incompatible changes will be incorporated into a new version.
- If there is a backward-incompatible change, we will issue a 90-day notice to announce it, and the backward-incompatible change will be deployed at least 90 days after the notice is issued.
- Deprecated versions (if any) will be unsupported, and developers are advised to stop using these APIs.
To learn more about our upgrades, please see our API changelog.