Verze FedEx API

Pro správu verzí API používáme ve společnosti FedEx sémantické verzování. Každá verze je reprezentována formátem verze major.minor (hlavní.vedlejší) (tj. rozhraní API Ship 1.1). Nová hlavní verze znamená, že změna je zpětně nekompatibilní a nová vedlejší verze označuje zpětně kompatibilní změnu.

Ve společnosti FedEx se řídíme jednoduchým verzováním URI. To zahrnuje uvedení pouze hlavního čísla verze, jež je v cestě URI reprezentováno. Upozorňujeme, že v cestě URI není zahrnuto číslo vedlejší verze. Tato strategie využívá směrování URI k určení konkrétních verzí API.

Příklad: /ship/v1/shipments

Hlavní principy strategie verzování

Plánujeme zveřejňování menšího počtu hlavních verzí pro rozhraní FedEx API tak, aby byla hlavní verze za dva roky od vydání novější hlavní verze zastaralá. Například, je zveřejněna hlavní verze „X“, verze „X-1“ bude podporována po dobu dvou let od vydání verze „X“

Příklad: V roce 2020 je zveřejněna hlavní verze V1.0. Pokud bude v roce 2021 vydána hlavní verze V2.0, bude pak V1.0 v roce 2023 zastaralá.

Vedlejší verze budou podporovat většinu nových funkcí a aktualizací funkcí.

Příklad: Po hlavní verzi 1.0 budou vydány vedlejší verze 1.1, 1.2 atd. obsahující nové funkce a aktualizace funkcí.

V kterémkoli okamžiku však budou mít všechny koncové body pro konkrétní API stejnou hlavní verzi. Nejnovější verze dokumentace bude k dispozici pouze na portálu FedEx Developer Portal. Na jednotlivých stránkách přehledu rozhraní API však bude k dispozici protokol změn, který podrobně popisuje změny v hlavní a vedlejší verzi.

Kdy jsou zveřejňovány hlavní verze API?

Počet hlavních verzí našich API se snažíme minimalizovat. Existují však určité případy, kdy je uvedení nové hlavní verze nevyhnutelné. Zde následuje několik klíčových důvodů, proč by se měla nová hlavní verze vydat:

• Když je stávající hodnota pole odebrána nebo byly formát či samotná hodnota změněny v požadavku či odpovědi
  

  Příklad: Hodnota pole „GEOGRAPHIC_COORDINATES“ (zeměpisné_souřadnice) pro prvek locationSearchCriterion je ve verzi X odstraněna; syntaxe data byla změněna z RR-MM-DD na MM-DD-RRRR; typ provozovny byl v odpovědi změněn z FEDEX_ONSITE na ONSITE

• Když je stávající prvek odebrán z požadavku nebo odpovědi
  

  Příklad: Prvek pickupType je ve verzi N odstraněn (nebo přejmenován) z cenového požadavku.

• Když je stávající metoda odstraněna
  

  Příklad: Metoda vytváření a zrušení štítků FedEx Express již není ve verzi N podporována

• Když je stávající prvek, jež byl dříve volitelný nebo podmíněný, nyní v požadavku povinný
  

  Příklad: Číslo rezervace je nyní ve verzi N povinný prvek pro zásilky FedEx Express® Freight

• Když dojde ke změně rozvržení rozhraní API
  

  Příklad: Je upravena struktura požadavku a odpovědi

• Když dojde ke změnám chybových kódů a chybových zpráv
  

  Příklad: Změna chybového kódu z INCORRECT.WEIGHT na WEIGHT.LIMIT.EXCEEDED

Kdy jsou vedlejší verze API zveřejňovány?

• Když je přidána nová hodnota pole
  

  Příklad: Nová nabídka dopravy je přidána do prvku serviceType ve verzi X

• Když je přidán nový prvek
  

  Příklad: Nový volitelný prvek, který zahrnuje telefonní číslo celního brokera pro mezinárodní zásilku

• Když je přidána nová metoda
  

  Příklad: Metoda úpravy dokumentů mezinárodního obchodu poté, co byly nahrány, je přidána ve verzi X.

• Když je stávající prvek, jež byl dříve povinný, změněn na volitelný
  

  Příklad: ID dokumentu je nyní volitelný prvek, protože FedEx dokáže odvodit ID dokumentu na základě informací o uživateli.