Versionshantering av FedEx API:er

FedEx använder semantisk versionshantering för att hantera API-versioner. Varje version har versionsformatet huvudversion.delversion (tex. API Skicka 1.1). En ny huvudversion betyder att ändringen inte är bakåtkompatibel och en ny delversion betyder att ändringen är bakåtkompatibel.

FedEx använder enkel URI-versionshantering. Det betyder att endast huvudversionsnumret visas i URI-sökvägen. Observera att delversionsnumret inte visas i URI-sökvägen. Den här strategin använder URI-sökvägar för att fastställa specifika versioner av API:er.

Exempel: /ship/v1/shipments

Riktlinjer för versionshantering

Vi planerar att lansera få huvudversioner för FedEx API:er och en äldre huvudversion blir inaktuell två år efter att en senare huvudversion har lanserats. Om till exempel huvudversion ”N” lanseras så kommer versionen ”N-1” att vara aktuell under två år efter lanseringen av version ”N”.

Exempel: Huvudversion V1.0 lanseras under 2020. Om huvudversion V2.0 lanseras under 2021 kommer V1.0 att bli inaktuell under 2023.

Version

Delversioner kommer att introducera de flesta av de nya funktionerna och funktionsuppdateringarna.

Exempel: Efter huvudversion 1.0 kommer delversion 1.1, 1.2 osv. att lanseras för att introducera nya funktioner och funktionsuppdateringar.

Alla slutpunkter för ett visst API kommer alltid att ha samma huvudversion. Endast den senaste versionen av dokumentationen kommer att vara tillgänglig på FedEx Developer Portal. Men det kommer att finnas en ändringslogg under varje API:s översiktssida med information om ändringarna i huvud- och delversionerna.

När lanseras huvudversioner av API:erna?

Vi strävar efter att minimera antalet huvudversioner av våra API:er. I vissa fall är det dock inte möjligt att undvika nya huvudversioner. Här följer några anledningar till att en ny huvudversion lanseras:

  • När ett befintligt fasttextvärde tas bort eller om formatet eller värdet har ändrats för svar eller förfrågningar

    Exempel: Fasttextvärdet “GEOGRAPHIC_COORDINATES” för elementet locationSearchCriterion tas bort från N-versionen, datumsyntaxen ändras från ÅÅ-MM-DD till MM-DD-ÅÅÅÅ och kontorstypen ändras från FEDEX_ONSITE till ONSITE för svar.

  • När ett befintligt element tas bort för svar eller förfrågningar

    Exempel: Elementet pickupType tas bort (eller döps om) från Begär pris i N-versionen.

  • När en befintlig metod tas bort

    Exempel: Metoden för att skapa och avbryta FedEx Express-etiketter stöds inte längre i N-versionen

  • När ett befintligt element ändras från valfritt eller villkorsstyrt till obligatoriskt för svar

    Exempel: Elementet Bokningsnummer ändras från valfritt till obligatoriskt för FedEx Express®-försändelser i N-versionen

  • När API:ets design ändras

    Exempel: Strukturen för förfrågningar och svar ändras

  • När felkoder och felmeddelanden ändras

    Exempel: En felkod ändras från INCORRECT.WEIGHT till WEIGHT.LIMIT.EXCEEDED

När lanseras delversioner av API:erna?

  • När ett nytt fasttextvärde läggs till

    Exempel: En ny transporttyp läggs till för elementet serviceType i N-versionen

  • När ett nytt element läggs till

    Exempel: Ett nytt valfritt element läggs till för agentens telefonnummer för internationella försändelser

  • När en ny metod läggs till

    Exempel: En ny metod för att ändra internationella handelsdokument efter att de har överförts läggs till i N-versionen.

  • När ett befintligt element ändras från obligatoriskt till valfritt

    Exempel: Dokument-ID ändras till ett valfritt värde eftersom FedEx kan hämta dokument-ID:t baserat på användarinformationen.

Vanliga frågor

Ni måste uppdatera URI:et till den senaste versionen inom två år för att FedEx ska kunna avveckla den äldre versionen. 

Delversioner lanseras för att introducera nya funktioner och ändringar som är bakåtkompatibla, och de kommer därför inte att påverka din integrering. Det är inte obligatoriskt att uppgradera till en ny delversion, men det rekommenderas generellt som bästa praxis att för att dra fördel av de nya funktionerna.

I FedEx webbtjänster kräver varje ändring en ny WSDL-version eller en ny huvudversion, vilket gör det svårare för kunder att uppgradera. Med FedEx API:er kan de flesta av de nya funktionerna introduceras med delversioner, vilket gör det enklare för kunder att uppgradera. Det kommer att lanseras fler delversioner av API:er och färre huvudversioner.