FedEx API-versionering

Hos FedEx bruger vi semantisk versionering til at administrere API-versioner. Hver version er repræsenteret af versionsformatet major.minor (dvs. Forsendelse af API 1.1). En ny større version betyder, at ændringen er bagudinkompatibel, mens en ny mindre version indikerer en bagudkompatibel ændring.

Hos FedEx følger vi simpel URI-versionering. Dette involverer kun det højeste versionsnummer, der er repræsenteret i URI-stien. Bemærk, at et mindre versionsnummer ikke er inkluderet i URI-stien. Denne strategi bruger URI-routing til at bestemme visse versioner af API'en.

Eksempel: /forsendelse/v1/forsendelser

Vejledende principper for versioneringsstrategi

Vi planlægger at udgive færre større versioner af FedEx API'er og afskriver en større version om to år efter udgivelsen af en nyere større version. For eksempel, hvis en større version 'N' udgives, understøttes 'N-1'-versionen i to år fra udgivelsen af version ‘N.’

Eksempel: I 2020 udgives en større version V1.0. Hvis der i 2021 frigives en større version V2.0, afskrives V1.0 i 2023.

Mindre versioner understøtter de fleste af de nye opdateringer af funktionalitet og funktioner.

Eksempel: Efter en større version 1.0 udgives de mindre versioner 1.1, 1.2 osv. for at introducere nye opdateringer af funktionalitet og funktioner.

På ethvert tidspunkt vil alle slutpunkter for en bestemt API have den samme større version. Den seneste version af dokumentationen vil kun være tilgængelig på FedEx Developer Portal. Der vil dog være en ændringslog på hver API's oversigtsside, der vil beskrive ændringer af de større og mindre versioner.

Hvornår udgives større API-versioner?

Vi prøver på at minimere antallet af større versioner for vores API'er. Der er dog visse tilfælde, hvor en ny større version ikke kan undgås. Følgende er nogle af de vigtigste grunde til, at en ny større version vil blive udgivet:

• Når en eksisterende opregningsværdi fjernes, eller format eller værdi i sig selv er ændret i anmodning eller svar
  

  Eksempel: Tællingsværdien “GEOGRAPHIC_COORDINATES” for locationSearchCriterion-elementet fjernes i N-version; datosyntaks ændres fra ÅÅ-MM-DD til MM-DD-ÅÅÅÅ; placeringstype ændres fra FEDEX_ONSITE til ONSITE i svar

• Når et eksisterende element fjernes i anmodning eller svar
  

  Eksempel: pickupType-elementet fjernes (eller omdøbes) fra prisanmodning i N-version

• Når en eksisterende metode fjernes
  

  Eksempel: Metoden til at oprette og annullere FedEx Express-mærker understøttes ikke længere i N-version

• Når et eksisterende element, der tidligere var valgfrit eller betinget, gøres obligatorisk i anmodningen
  

  Eksempel: Bookingnummer er nu et obligatorisk element for FedEx Express® fragtforsendelser i N-version

• Når der er API-designændringer
  

  Eksempel: Anmodning og svarstruktur er omarrangeret

• Når der er ændringer med fejlkoder og fejlmeddelelser
  

  Eksempel: Ændring af fejlkode fra INCORRECT.WEIGHT til WEIGHT.LIMIT.EXCEEDED

Hvornår udgives mindre API-versioner?

• Når der tilføjes en ny optællingsværdi
  

  Eksempel: Der tilføjes et nyt transporttilbud til serviceType-elementet i N-version

• Når der tilføjes et nyt element
  

  Eksempel: Et nyt valgfrit element til at inkludere mæglertelefonnummer for international forsendelse

• Når en ny metode tilføjes
  

  Eksempel: Der tilføjes en metode i N-version til at ændre internationale handelsdokumenter, når de er uploadet.

• Når et eksisterende element, der plejede at være påkrævet, gøres valgfrit
  

  Eksempel: Dokument-ID er nu valgfrit, fordi FedEx kan udlede dokumentations-ID baseret på brugeroplysninger.