API versioning

An API version must be specified by providing an API header of X-Ascenda-Version. The current latest stable API version is 1.3.

Most changes to the Ascenda API are backwards compatible (e.g. adding new attributes, new optional request parameters) and will not result in a new API version. However, in cases where a backwards compatible change is not possible, Ascenda will bump the API version to ensure backwards compatibility with your existing platform which might still be integrated with the current lower version.

Major & Minor Versioning

API version upgrades are effortful. Ascenda aims to avoid breaking changes where possible (see our Backwards Compatibility guidelines below).

Typically we increase the minor version whenever we introduce breaking change to an API (going from 1.2 to 1.3 for example). Minute (but breaking changes) may be prefaced with a smaller version change like 1.2.1
We only increase the major version if we have a major structural change across most of our existing APIs.
When a new minor version is introduced, it is marked as Unstable until we deem them as Stable and mark it as so here in our documentation.
- When a version is Unstable, we may introduce further fixes that causes breaking change to the API endpoints.
- You should rely on the Stable version only, with Unstable version being used only in testing environment.

Backwards Compatible Changes

The following kinds of updates are backwards-compatible:

New attributes to API requests & responses
New API endpoints
Parameter updates in our existing API endpoints
- Length validations
- Formatting updates of strings
- Response updates to string values such as error messages
New event types in our webhooks. Your application needs to handle unspecified event types gracefully

Upgrading your API Version

If you’re running an older version of the API, upgrade to the latest version to take advantage of new functionality or to streamline responses so the API is faster for you.

When you upgrade your version:

API calls without X-Ascenda-Version header will always be served with the latest version of our APIs
Structure of passthrough objects sent to your webhook endpoints. Our webhooks will always reflect the latest object structure received in the APIs

After 6 months, Ascenda will typically remove older versions. This allows us to keep our platforms lean & flexible without being saddled by technical debt of deprecated versions.

Please contact your account manager or submit a ticket to request for help if you need longer term support for your API version.

Communicating breaking changes

For major upgrades to our APIs in your integrations, you'll find them in our Changelog.

Some changes to our endpoints might not be backward-compatible. For example, adding a required field or removing a field from a response could break existing integrations. In contrast, adding an optional field to a request or response would be an additive change.

When non-backward-compatible changes are made, you'll receive a notice of upgrades from our customer success and technical operations teams. We increment the API version to preserve backwards compatibility for you.

We consider breaking changes (that don’t involve full deprecation) to require less effort from developers, though they can still cause significant disruption. Therefore, the communication lead time for breaking changes is shorter than for deprecations. During this phase, we send reminders to the affected consumers of the endpoints/API.

Major version upgrade notice is sent 12 months in advance
Deprecation notice
- 6 months to deprecation: Initial notice
- 5 months to deprecation: Reminder notice and acknowledgement request
- 3 months to deprecation: Third reminder
- 1 month to deprecation: Fourth reminder
- 1 week to deprecation: Fifth reminder
- Day after deprecation: We announce that changes have been performed over email updates