FedEx API versioning
At FedEx, we use semantic versioning to manage API versions. Each version is represented by the version format of major.minor (i.e., Ship API 1.1). A new major version means that the change is backwards-incompatible, and a new minor version indicates a backwards-compatible change.
At FedEx, we follow simple URI versioning. This involves only the major version number being represented in the URI path. Please note that a minor version number is not included in the URI path. This strategy uses URI routing to pinpoint particular versions of the API.
Versioning strategy guiding principles
We plan on releasing fewer major versions for FedEx APIs and deprecating a major version in two years from the release of newer major version. For example, of a major version ‘N’ is released, ‘N-1’ version will be supported for two years from the release of version ‘N.’
Example: In 2020, major version V1.0 is released. If in 2021, major version V2.0 is released, then V1.0 will be deprecated in 2023.
Minor versions will support most of the new functionality and feature updates.
Example: Post major version 1.0, minor versions 1.1, 1.2, etc. will be released to introduce new functionality and feature updates.
At any point in time, all endpoints for a particular API will have the same major version. The latest version of the documentation will only be available on the FedEx Developer Portal. However, there will be a change log under each API’s Overview page that will detail out the major and minor version changes.
When are API major versions released?
We are striving to minimize the number of major versions for our APIs. However, there are certain cases where a new major version is unavoidable. The following are some of the key reasons why a new major version would be released:
- When an existing enumeration value is removed or format or value itself has changed in request or response
Example: The enumeration value “GEOGRAPHIC_COORDINATES” for locationSearchCriterion element is removed in N version; date syntax is changed from YY-MM-DD to MM-DD-YYYY; changing location type from FEDEX_ONSITE to ONSITE in response
- When an existing element is removed in request or response
Example: pickupType element is removed (or renamed) from rate request in N version
- When an existing method is removed
Example: The method to create and cancel FedEx Express tags is no longer supported in N version
- When an existing element that used to be optional or conditional is made mandatory in the request
Example: Booking number is now a mandatory element for FedEx Express® Freight shipments in N version
- When there are API design changes
Example: Request and response structure is rearranged
- When there are changes with error codes and error messages
Example: Changing error code from INCORRECT.WEIGHT to WEIGHT.LIMIT.EXCEEDED
When are API minor versions released?
- When a new enumeration value is added
Example: A new transportation offering is added for serviceType element in N version
- When a new element is added
Example: A new optional element to include broker phone number for international shipment
- When a new method is added
Example: A method to modify international trade documents after they are uploaded is added in N version.
- When an existing element that used to be required is made optional
Example: Document ID is now optional because FedEx can derive the documentation ID based on user information.
You will have to update the URI to the latest version within two years so FedEx can retire the older version.
Minor versions are released to accommodate new features and changes that are backwards-compatible and therefore not expected to break your integration. It is not a requirement to upgrade to a new minor version, but it is generally recommended as a best practice to upgrade to minor versions to consume the new features that are created to address customer needs.
In FedEx Web Services, every change requires a new WSDL release or a major version, making upgrades harder for customers. With FedEx APIs, most of the new features can be introduced through minor versions, making it easier for customers to upgrade. There will be more API minor versions and fewer major versions.