FedEx API verziószámozás

A FedEx-nél szisztematikus verziószámozással kezeljük az API-k verzióit. Mindegyik verziót főverziószám.alverziószám formátumú verziószámmal jelöljük (például: Szállítási API 1.1). Egy új főverziószám azt jelenti, hogy a módosítás visszafelé nem kompatibilis, míg a egy új alverziószám visszafelé kompatibilis módosítást jelez.

A FedEx-nél egyszerű URI-verziószámozást használunk. Ez azt jelenti, hogy az URI elérési útvonalon csak a főverziószám jelenik meg. Felhívjuk a figyelmét arra, hogy az alverziószám nem része az URI elérési útvonalnak. Ez a stratégia URI elérési útvonalakkal határozza meg az API konkrét verzióit.

Példa: /szállítás/v1/küldemények

A verziószámozási stratégia vezérelvei

Azt tervezzük, hogy a FedEx API-knak kevesebb fő verzióját adjuk ki, és egy fő verziót egy újabb fő verzió kiadásától számított két év múlva érvénytelenítünk. Például egy „N” fő verzió kiadása esetén az „N” verzió kiadásától számított két évig támogatjuk az „N-1” verziót.
Példa: 2020-ban kiadtuk a V1.0-s fő verziót. Ha 2021-ben kiadjuk a V2.0-s fő verziót, akkor a V1.0-s verziót 2023-ban fogjuk érvényteleníteni.

Az alverziók a legtöbb új funkciót és funkciófrissítést támogatni fogják.

Példa: Az 1.0-s verzió után az 1.1-es, az 1.2-es stb. alverziók kiadásával fogunk bevezetni új funkciókat és funkciófrissítéseket.

Egy-egy konkrét API-nak bármelyik időpontban minden végpontja ugyanolyan főverziószámú lesz. A dokumentáció legfrissebb verziója csak a FedEx Developer Portalon lesz elérhető. Azonban mindegyik API Áttekintés oldalán megtalálható lesz a módosítások naplója, amely részletesen ismerteti a fő és alverziókban végrehajtott változtatásokat.

Mikor adunk ki új fő verziót az API-kból?

Igyekszünk minimalizálni API-ink fő verzióinak számát. Vannak azonban olyan esetek, amikor elkerülhetetlen egy új fő verzió. Az alábbiakban felsoroljuk az új fő verziók kiadásának néhány főbb okát:

• Amikor megszűnik egy addig meglévő felsorolásos típusú érték, vagy egy kérésben vagy válaszban megváltozik a formátum vagy maga az érték.
  

  Példa: A locationSearchCriterion elem „GEOGRAPHIC_COORDINATES” felsorolásos típusú értéke megszűnik az N verzióban; a dátum formátuma ÉÉ-HH-NN formátumról HH-NN-ÉÉÉÉ formátumra módosul; a kirendeltség típusa FEDEX_ONSITE-ról ONSITE-ra módosul a válaszban.

• Amikor egy addig meglévő elemet eltávolítunk egy kérdésből vagy válaszból.
  

  Példa: A pickupType elemet eltávolítjuk (vagy átnevezzük) a tarifa lekérésében az N verzióban.

• Amikor eltávolítunk egy meglévő metódust.
  

  Példa: A FedEx Express címkéket létrehozó és törlő metódus többé nem támogatott az N verzióban.

• Amikor egy meglévő, korábban nem kötelező vagy feltételes elemet kötelezővé teszünk egy kérésben.
  

  Példa: A foglalási szám már kötelező elem a FedEx Express® Freight küldemények esetén az N verzióban.

• Amikor megváltozik az API felépítése.
  

  Példa: Átszervezésre került a kérés és a válasz struktúrája.

• Amikor megváltoznak a hibakódok és a hibaüzenetek.
  

  Példa: Az INCORRECT.WEIGHT hibakód WEIGHT.LIMIT.EXCEEDED-re módosul.

Mikor adunk ki új alverziót az API-kból?

• Amikor bővül a felsorolásos típusú értékek listája.
  

  Példa: A serviceType elem kiegészült egy új szállítási ajánlattal az N verzióban.

• Amikor hozzáadunk egy új elemet.
  

  Példa: Egy új, nem kötelező elemmel bevehető a vámbróker telefonszáma nemzetközi küldemény esetén.

• Amikor hozzáadunk egy új metódust.
  

  Példa: Az N verzióban hozzáadtunk egy olyan új metódust, amellyel feltöltésük után módosíthatók a nemzetközi kereskedelmi dokumentumok.

• Amikor egy meglévő, korábban kötelező elem nem kötelezővé válik.
  

  Példa: A dokumentumazonosító már nem kötelező, mert a FedEx a felhasználó adatai alapján meg tudja határozni a dokumentumazonosítót.