Versioning

Each request to the Duffel API must include a Duffel-Version header so we know which version of the API you want to use.

During our beta programme, we may make backwards-incompatible changes to the API at short notice. When we do, you may need to make changes to your integration, or it'll stop working.

Availability period

When we release a new version of the API, the previous version will be available for 6 months. It will no longer be available or usable after that time.

New API versions will be released with backwards-incompatible changes. Backwards-compatible changes may be added to the latest version. In case we mark parts of the API as deprecated, they'll be removed in the next API version.

Available API versions which predate the latest generally available version will be patched with bug and security fixes, where possible.

Changes in versions

Backwards-incompatible changes

We generally consider the following as backwards-incompatible changes:

  • Adding a new required request body or query string parameter
  • Changing the name of a required request body or query string parameter
  • Removing a required request body or query string parameter
  • Removing an existing endpoint
  • Removing any field in the response (whether required or optional)
  • Restructuring of the input or output format (e.g., making a top-level field a sub-field, or changing the location of errors to be inline)
  • Changing a name of a field in the response
  • Changing a resource name, such as Offer or Order
  • Changing a HTTP response code
  • Changing type and code attributes of API errors
  • Changing existing behaviour (e.g. segments that were previously returned with a default sorting order not being ordered in that way)

Backwards-compatible changes

We consider the following as backwards-compatible changes:

  • Adding a new optional request body or query string parameters
  • Adding new API endpoints
  • Adding new attributes to responses from existing API endpoints
  • Reordering attributes in responses from existing API endpoints
  • Adding a value to an existing enumeration
  • Changing format or length of IDs
  • Changing title or message attributes of API errors
  • Adding new types of services, e.g. meals, fast track boarding, and WiFi access.

Communicating changes

All of our API changes are posted to our changelog. Before we make any breaking changes, we'll email details to registered users as well.

Migration guides

For each version, we will publish a migration guide from the previous version to the new one that explains the changes you need to make to upgrade your integration.

Client libraries

The API client libraries which we maintain will be updated when a new version is released so that they're always on the latest version.

Any client library versions that use an older version will eventually stop working as the API version they use falls out of availability.

Versioned instances of client libraries are installed by package managers so you may pin a specific version instead of always updating to the latest version of that package. Our client libraries use semantic versioning. The version of a client library package will not reflect the API version it uses when connecting to the Duffel API.