This page provides guidelines on how we handle different versions of the API to ensure compatibility and stability. Users can learn how to work with specific API versions, understand versioning policies, and manage updates seamlessly.
API versioning
An API version can be specified by providing an API header of X-Ascenda-Version. The current latest stable API version is 1.3. If not specified, the latest stable API version is assumed.
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.2to1.3for example). Minute (but breaking changes) may be prefaced with a smaller version change like1.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-Versionheader 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