Your API version has a large impact on your experience with Flexport's APIs. Currently, there are three versions available for consumption. You can see your account's current API version in your API settings page.
If you'd like to change your account's API version, please reach out to integration support (integration-support@flexport.com) for the operation.
Your account's default API version can always be overridden by passing in the Flexport-Version header when
making an API request.
Flexport introduces a revolutionary approach to versioning API endpoints by implementing a precise and helpful backwards compatible date-based versioning system. Unlike traditional numeric versioning systems, date-based versioning is time-oriented and offers numerous advantages. It not only carries more meaningful information but also enables the independent evolution of individual API endpoints.
In numeric versioning, all API endpoints must be upgraded to the next version, regardless of any changes made to them. This lack of flexibility results in decreased agility and longer deployment times for new versions. However, with date-based versioning, any API endpoint can introduce a new version independently, without requiring changes to other API endpoint versions.
Similar to numeric versioning, the version is transmitted in the HTTP Flexport-Version header. The value of a date-based version
consists of a 10-character date format (YYYY-MM-DD). It is crucial for the provided date-based version to be both a valid calendar
date and not one in the future. A future date is defined as any date greater than the UTC date at the moment the API request is
processed by Flexport.
It is important to note that the date does not have to match the exact date of any specific API endpoint's date-based version. It can be any valid date on or after a given version date. Nonetheless, the API version resolves to the version of the API endpoint as if the API was called on that particular date.
For instance, if an API is released with version 2023-01-01 and later with version 2023-05-11, calling the API with a version of 2023-02-15 would resolve to the first version. Any version with a valid date on or after 2023-05-11 would resolve to the second version.
Furthermore, date-based versioning removed the ability of associating a default API version with the client account. In order for date-based version API requests to be successfully processed, a version must be provided in the HTTP header.
Nevertheless, it is possible to use a single date to access all API endpoints, and it would resolve to the API versions as of that date. In order to enable date-based versions to access numeric version APIs, we support mapping from date versions to numeric versions. This mapping is evaluated in the following sequence, any valid date on or after 2023-01-01 would map to numeric version 3 on or after 2022-01-01 would map to numeric version 2 on or after 2021-01-01 would map to numeric version 1
Flexport considers some changes to be non-breaking and will make those changes without updating the API version. Please follow defensive coding practices in order to ensure stability. We consider the following to be backwards-compatible changes:
enum type attribute.