Versions des API FedEx

Chez FedEx, nous utilisons le versionnage sémantique pour gérer les versions des API. Chaque version est représentée par le format de version majeure.mineure (c’est-à-dire, API d’expédition 1.1). Une nouvelle version majeure signifie que le changement n’est pas rétrocompatible, et une nouvelle version mineure indique un changement rétrocompatible.

Chez FedEx, nous suivons un système de versionnage URI simple. Cela implique que seul le numéro de la version majeure est représenté dans le chemin de l’URI. Le numéro de version mineure n’est pas inclus dans le chemin de l’URI. Cette stratégie utilise le routage URI pour localiser des versions particulières de l’API.

Exemple : /expédition/v1/envois

Principes directeurs de la stratégie de gestion des versions

Nous prévoyons de publier moins de versions majeures pour les API FedEx et déclarer obsolète une version majeure dans les deux ans suivant la publication d’une version majeure plus récente. Par exemple, si une version majeure « N » est publiée, la version « N-1 » sera prise en charge pendant deux ans à compter de la publication de la version « N ».

Exemple :en 2020, la version majeure V1.0 est publiée. Si en 2021 la version majeure V2.0 est publiée, la version V1.0 sera alors déclarée obsolète en 2023.

Les versions mineures prendront en charge la plupart des nouvelles fonctionnalités et mises à jour.

Exemple : après la version majeure 1.0, des versions mineures 1.1, 1.2, etc. seront publiées pour introduire de nouvelles fonctionnalités et des mises à jour.

Tous les terminaux d’une API particulière auront la même version majeure tout le temps. La dernière version de la documentation ne sera disponible que sur le FedEx Developer Portal. Toutefois, il y aura un journal des modifications sous la page d’aperçu de chaque API qui détaillera les changements de version majeure et de version mineure.

Quand les versions majeures des API sont-elles publiées ?

Nous nous efforçons de minimiser le nombre de versions majeures pour nos API. Toutefois, il existe certains cas où une nouvelle version majeure est inévitable. Voici quelques-unes des principales raisons pour lesquelles une nouvelle version majeure serait publiée :

• Lorsqu’une valeur d’énumération existante est supprimée ou que le format ou la valeur elle-même a changé dans la requête ou la réponse.
  

  Exemple : la valeur d’énumération « COORDONNÉES_GÉOGRAPHIQUES » pour l’élément locationSearchCriterion est supprimée dans la version N ; la syntaxe de la date passe de AA-MM-JJ à MM-JJ-AAAA ; le type de lieu passe de FEDEX_ONSITE à ONSITE en réponse.

• Lorsqu’un élément est supprimé de la requête ou de la réponse.
  

  Exemple : l’élément pickupType est supprimé (ou renommé) de la demande de tarif dans la version N.

• Lorsqu’une méthode existante est supprimée.
  

  Exemple : la méthode de création et d’annulation des étiquettes FedEx Express n’est plus prise en charge dans la version N.

• Lorsqu’un élément existant qui était facultatif ou conditionnel est rendu obligatoire dans la requête.
  

  Exemple : le numéro de réservation est désormais un élément obligatoire pour les envois de colis FedEx Express® en version N.

• Lorsqu’il y a des changements dans la conception des API.
  

  Exemple : la structure des demandes et des réponses est réorganisée.

• Lorsqu’il y a des changements avec des codes d’erreur et des messages d’erreur.
  

  Exemple : modification du code d’erreur de POIDS.INCORRECT à LIMITE.POIDS.DÉPASSÉE.

Quand les versions mineures des API sont-elles publiées ?

• Lorsqu’une nouvelle valeur de dénombrement est ajoutée.
  

  Exemple : une nouvelle offre de transport est ajoutée pour l’élément serviceType dans la version N.

• Lorsqu’un nouvel élément est ajouté.
  

  Exemple : un nouvel élément facultatif permettant d’inclure le numéro de téléphone du courtier pour l’envoi international.

• Lorsqu’une nouvelle méthode est ajoutée.
  

  Exemple : une méthode permettant de modifier les documents commerciaux internationaux après leur chargement est ajoutée dans la version N.

• Lorsqu’un élément existant qui était exigé est rendu facultatif.
  

  Exemple : l’ID du document est désormais facultatif car FedEx peut le récupérer à partir des informations de l’utilisateur.