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.
In our beta version, 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.
Versions
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.