Breaking changes
The Understory API is versioned in major versions.
Breaking changes are changes that can potentially break an integration. Below is a non-exhaustive list of what breaking changes could be.
- Removing an operation
- Renaming or removing a parameter, request, and/or response field
- Significantly changing the behavior of an endpoint, e.g.,
POST /v1/bookingschanges from creating a booking to reserving seats at an event for later booking confirmation.
We will add new fields to the APIs and expect these to be consumed in a non-breaking fashion by your integration. This usually means configuring request/response serializers to accept unknown fields to avoid disruption.
When a new version of the API is released, the previous API version is deprecated and will move into a grace period, where it will be available for 6 months. During this grace period, you will need to migrate your integration to the new API versions to avoid service disruption.
For more information on versioning, see API Versioning.
Upgrading to a new version
Before upgrading to a new major version consult the changelog to understand the details of the changes. Depending on the changes to the API and your integration, you might have no or several changes to implement to support the new version.
As a minimum you are required to update the version HTTP path segment to the new major.
curl https://api.understory.io/v1/bookings
curl https://api.understory.io/v2/bookings When updating the integration to use the new major versions, make sure to test that it works as you intend before releasing it.