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.

Example: /ship/v1/shipments

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.