Last updated

API Versioning

This document describes how the Understory API is versioned.

About API versions

All resources on the API are prefixed with a major version number, e.g., /v1/bookings. Any breaking changes to an API will be released as a new major version in the path, and existing API versions will continue to work within the grace period.

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/bookings changes 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.

Stable, Previews and Alpha APIs

Understory will release new API specifications as early as possible to gather feedback. This means that APIs in the API Reference can be labeled with two labels depending on their state. APIs without a label in the reference are considered stable and follow the general versioning scheme as described in this document.

  • Preview: The API is not available in production and cannot be used. The specification is shared only as a preview of what might come. Breaking changes are likely to occur.
  • Alpha: The API is available in production and can be used. The specification is close to stable but we still test things out ensuring the model is sound.

Specifying an API version

For each resource, the API version is defined as an HTTP path segment. To use a specific version thus means to request the resource with the correct path.

Below are two examples of requesting a list of bookings. Be advised that these are examples and that there is currently no v2 of the bookings resources.

Request bookings from version 1
curl https://api.understory.io/v1/bookings
Request bookings from version 2
curl https://api.understory.io/v2/bookings

See also

Back
Next