Alpha / Beta API Versioning
During the alpha and beta phases of the API and new endpoints, we will mark the version as
v0in the path, for example:
Please expect the model to change frequently as we receive feedback from early adopters. Once we transition to beta, breaking changes will begin to stop and we'll be transitioning to
The Spendesk API is versioned via a major version number in the path, for example
https://public-api.spendesk.com/v1/payables. Only backwards compatible changes will be made within this path version to ensure it does not break any integrations. Examples of backwards compatible changes:
- Addition of any optional fields or parameters in the request or response model (that don't change the structure of the model)
- Addition of a new endpoint or optional capability
In the scenario where we cannot avoid make breaking / backwards incompatible changes, we will major version the path, for example
https://public-api.spendesk.com/v2/payables. Example of these breaking changes:
- Additional required request fields or parameters
- Removal or renaming of models, fields or parameters
- Removal of an endpoint or capability
When adding new ENUM fields, although considered a breaking change, we will in general not release a new major version the path. When this occurrence happens we will coordinate with consumers.
When a new version of the API will be added, we will bump the version number of the version in the path (e.g. from
/v2/). The previous version will continue to be supported for a defined amount of time, and an Upgrade Guide will be added to the Developer Portal.
As we manage the lifecycle of an API, we may decide to deprecate endpoint(s). Deprecated endpoints will no longer receive support and updates but will still work until sunsetted. When an endpoint is deprecated, we encourage you to migrate to the new version. In general, we will endeavour to support the latest (n) and n-1 versions of the endpoint.
If an endpoint is due for deprecation, responses will contain the header
Deprecation in date-time format, for example:
After deprecation, we may sunset endpoint(s). Sunsetted endpoints will no longer be available to use and the consumer will have to migrate to the latest version. Similar to deprecation, a
Sunset header in date-time format will be included in each response. For example:
Updated 10 days ago