Versionarea API FedEx

La FedEx, utilizăm versionarea semantică pentru a gestiona versiunile API. Fiecare versiune este reprezentată de formatul versiunii major.minor (și anume, API de expediere 1.1). O nouă versiune majoră se referă la o modificare incompatibilă în sens invers și o nouă versiune minoră indică o modificare compatibilă în sens invers.

La FedEx, urmăm o versionare URI simplă. Astfel, doar numărul versiunii majore este reprezentat în calea URI-ului. Observați că nu este inclus un număr al versiunii minore în calea URI-ului. Această strategie utilizează rutarea URI pentru a repera anumite versiuni ale API-ului.

Exemplu: /ship/v1/shipments

Principiile directoare ale strategiei de versionare

Intenționăm să lansăm mai puține versiuni majore pentru API-urile FedEx și să perimăm o versiune majoră la doi de la lansarea unei noi versiuni majore. De exemplu, dacă va fi lansată versiunea majoră „N”, versiunea „N-1” va fi acceptată o perioadă de doi ani de la lansarea versiunii „N”.

Exemplu: În 2020, este lansată versiunea majoră V1.0. Dacă în 2021, se lansează o versiune majoră V2.0, atunci V1.0 va fi perimată în 2023.

Versiunile minore vor accepta o mare parte dintre noile actualizări de funcționalități și caracteristici.

Exemplu: O versiune majoră ulterioară versiunii majore 1.0 sau versiunile minore 1.1, 1.2 etc. vor fi lansate pentru a introduce noi actualizări de funcționalități și de caracteristici.

În orice moment, toate punctele finale pentru un anumit API vor avea aceeași versiune majoră. Cea mai recentă versiune a documentației va fi disponibilă doar pe FedEx Developer Portal. Cu toate acestea, va exista un jurnal de modificări în cadrul fiecărei pagini Prezentare generală a API-ului, care va detalia modificările versiunilor majore și minore.

Când sunt lansate versiunile majore ale unui API?

Ne străduim să reducem numărul de versiuni majore pentru API-urile noastre. Cu toate acestea, există unele cazuri în care o nouă versiune majoră este inevitabilă. În continuare, vă prezentăm unele dintre motivele esențiale pentru care o nouă versiune majoră ar fi lansată:

• Când o valoare de enumerare existentă este eliminată sau formatul sau valoarea în sine s-a schimbat în solicitare sau răspuns
  

  Exemplu: Valoarea de enumerare „COORDONATE GEOGRAFICE” pentru elementul locationSearchCriterion este eliminată din versiunea N; sintaxa datei este modificată de la AA-LL-ZZ la LL-ZZ-AAAA; modificarea tipului de locație de la FEDEX_ONSITE la ONSITE în răspuns

• Când un element existent este eliminat din solicitare sau din răspuns
  

  Exemplu: elementul pickupType este eliminat (sau redenumit) din solicitarea tarifelor în versiunea N

• Când este eliminată o metodă existentă
  

  Exemplu: Metoda de creare și anulare a etichetei FedEx Express nu mai este acceptată în versiunea N

• Când un element existent care era opțional sau condițional este făcut obligatoriu în solicitare
  

  Exemplu: Numărul de rezervare este acum un element obligatoriu pentru expedierile FedEx Express® Freight în versiunea N

• Când sunt modificări de design API
  

  Exemplu: Structura de solicitare și de răspuns este reorganizată

• Când sunt modificări cu coduri de eroare și mesaje de eroare
  

  Exemplu: Modificarea codului de eroare de la INCORRECT.WEIGHT la WEIGHT.LIMIT.EXCEEDED

Când sunt lansate versiunile minore API?

• Când este adăugată o nouă valoare de enumerare
  

  Exemplu: O nouă ofertă de transport este adăugată pentru elementul serviceType în versiunea N

• Când este adăugat un nou element
  

  Exemplu: Un nou element opțional în scopul de a include numărul de telefon al brokerului pentru expedierea internațională

• Când este adăugată o nouă metodă
  

  Exemplu: O metodă de modificare a documentelor comerciale internaționale, după ce acestea sunt încărcate, este adăugată în versiunea N.

• Când este făcut opțional un element existent care era obligatoriu
  

  Exemplu: ID-ul documentului este acum opțional deoarece FedEx poate deriva ID-ul documentației pe baza informațiilor privind utilizatorul.