Zarządzanie wersjami interfejsu API FedEx

W FedEx używamy semantycznej obsługi wersji do zarządzania wersjami API. Każda wersja jest reprezentowana przez format wersji główna.pomocnicza (tj. interfejs API wysyłki 1.1). Nowa wersja główna oznacza, że zmiana jest niezgodna z poprzednimi wersjami, a nowa wersja pomocnicza oznacza zmianę zgodną z poprzednimi wersjami.

W FedEx stosujemy proste zarządzanie wersjami URI. Dotyczy to tylko numeru wersji głównej reprezentowanego w ścieżce URI. Numer wersji pomocniczej nie jest zawarty w ścieżce URI. Ta strategia wykorzystuje routing URI w celu wskazania konkretnych wersji interfejsu API.

Przykład: /ship/v1/shipments

Zasady przewodnie strategii zarządzania wersjami

Planujemy wydawanie mniejszej liczby wersji głównych interfejsów API FedEx i wycofywanie wersji głównej w ciągu dwóch lat od wydania nowszej wersji głównej. Przykład: po wydaniu wersji N wersja N-1 będzie obsługiwana jeszcze przez dwa lata.

Przykład: w 2020 roku została wydana wersja główna 1.0. W 2021 roku zostanie wydana wersja główna 2.0. W związku z tym wersja 1.0 zostanie wycofana w 2023 roku.

Wersje pomocnicze będą obsługiwać większość nowych funkcji i aktualizacji funkcji.

Przykład: Po wersji głównej 1.0 będą publikowane wersje pomocnicze 1.1, 1.2 itp. z nowymi funkcjami i aktualizacjami funkcji.

W dowolnym momencie wszystkie punkty końcowe dla konkretnego interfejsu API będą miały tę samą wersję główną. Najnowsza wersja dokumentacji będzie dostępna tylko w FedEx Developer Portal. Jednak pod stroną Przegląd każdego interfejsu API będzie dostępny dziennik zmian, w którym będą wyszczególnione zmiany w wersjach głównych i pomocniczych.

Kiedy są wydawane wersje główne interfejsów API?

Staramy się minimalizować liczbę wersji głównych interfejsów API. Są jednak przypadki, w których nowa wersja główna jest nieunikniona. Oto niektóre z głównych powodów, dla których zostałaby wydana nowa wersja główna:

• W przypadku usunięcia istniejącej wartości wyliczenia, ewentualnie w przypadku zmiany formatu lub samej wartości w żądaniu lub odpowiedzi
  

  Przykład: wartość wyliczania „GEOGRAPHIC_COORDINATES” dla elementu locationSearchCriterion została usunięta w wersji N; składnia daty została zmieniona z RR-MM-DD na MM-DD-RRRR; zmiana typu lokalizacji z FEDEX_ONSITE na ONSITE w odpowiedzi

• W przypadku usunięcia istniejącego elementu w żądaniu lub odpowiedzi
  

  Przykład: element pickupType został usunięty (lub zmieniono jego nazwę) z żądania stawki w wersji N.

• W przypadku usunięcia istniejącej metody
  

  Przykład: metoda tworzenia i anulowania etykiet FedEx Express Tag nie jest już obsługiwana w wersji N

• W przypadku gdy istniejący element, który był opcjonalny lub warunkowy, staje się obowiązkowy w żądaniu
  

  Przykład: numer rezerwacji jest teraz obowiązkowy dla przesyłek FedEx Express® Freight w wersji N

• W przypadku wprowadzenia zmian w projekcie interfejsu API
  

  Przykład: struktura żądania i odpowiedzi została zmieniona

• W przypadku wprowadzenia zmian związanych z kodami błędów i komunikatami o błędach
  

  Przykład: zmiana kodu błędu z INCORRECT.WEIGHT na WEIGHT.LIMIT.EXCEEDED

Kiedy są wydawane wersje pomocnicze interfejsów API?

• W przypadku dodania nowej wartości wyliczania
  

  Przykład: dla elementu serviceType w wersji N dodano nową usługę transportową

• W przypadku dodania nowego elementu
  

  Przykład: nowy element opcjonalny obejmujący numer telefonu brokera dla wysyłki międzynarodowej

• W przypadku dodania nowej metody
  

  Przykład: W wersji N dodano metodę modyfikacji międzynarodowych dokumentów handlowych po ich przekazaniu.

• W przypadku ustawienia istniejącego elementu wymaganego jako opcjonalnego
  

  Przykład: identyfikator dokumentu jest teraz opcjonalny, ponieważ FedEx może uzyskać identyfikator dokumentacji na podstawie informacji o użytkowniku.