DocumentationChangelog
Documentation
Login

Versioning & Deprecation

Versioning

The Spendesk API is versioned via a major version number in the path, for example https://public-api.spendesk.com/v1/settlements. 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/settlements. 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

📘

Additional Enumerators

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.

Adding a new version of the API

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 /v1/ to /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.

Deprecation

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: Deprecation: 2023-10-01T23:59:59Z

Sunsetting

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: Sunset: 2024-01-01T23:59:59Z