Versionnage 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 (par exemple, API d’expédition 1.1). Une nouvelle version majeure signifie que le changement n’est pas rétrocompatible, alors qu'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 versionnage

Nous prévoyons de publier moins de versions majeures pour les API FedEx et de 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 déclarée obsolète en 2023.

Version

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

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 de fonctions.

Tous les terminaux d’une API particulière auront la même version majeure en tout 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 réduire 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 demande ou la réponse.

    Exemple : la valeur d’énumération « GEOGRAPHIC_COORDINATES » 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 existant est supprimé de la demande ou de la réponse.

    Exemple : l’élément pickupType est supprimé (ou renommé) dans la demande de tarif de 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 demande.

    Exemple : le numéro de réservation est désormais un élément obligatoire pour les envois de fret FedEx ExpressMD 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 aux codes d’erreur et aux messages d’erreur.

    Exemple : le code d’erreur est modifié de INCORRECT.WEIGHT à WEIGHT.LIMIT.EXCEEDED.

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

  • Lorsqu’une nouvelle valeur d’énumération 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 permet d’inclure le numéro de téléphone du courtier pour un envoi international.

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

    Exemple : une méthode permettant de modifier les documents commerciaux internationaux après leur téléversement 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 renseignements de l’utilisateur.

Foire aux questions

Vous devrez mettre à jour l’URI à la dernière version dans un délai de deux ans afin que FedEx puisse retirer l’ancienne version. 

Des versions mineures sont publiées pour tenir compte des nouvelles fonctionnalités et des changements rétrocompatibles. Elles ne devraient donc pas interrompre votre intégration. Il n’est pas obligatoire de passer à une nouvelle version mineure, mais il est généralement recommandé comme meilleure pratique de passer à des versions mineures pour utiliser les nouvelles fonctionnalités qui sont créées pour répondre aux besoins des clients.

Dans les services Web de FedEx, chaque changement nécessite une nouvelle version du WSDL ou une version majeure, ce qui rend les mises à jour plus difficiles pour les clients. Avec les API FedEx, la plupart des nouvelles fonctionnalités peuvent être introduites par le biais de versions mineures, ce qui facilite la mise à niveau pour les clients. Il y aura davantage de versions mineures des API et moins de versions majeures.