FedEx-API versie

Bij FedEx gebruiken we semantische versies om de API-versies te beheren. Elke versie wordt vertegenwoordigd door het versieformaat van hoofd/onder (d.w.z. Verzend-API 1.1). Een nieuwe hoofdversie betekent dat de wijziging niet met terugwerkende kracht wordt ondersteund en een nieuwe onderversie geeft aan dat de wijziging wel met terugwerkende kracht wordt ondersteund.

Bij FedEx werken we met eenvoudige URI-versies. Dit houdt in dat alleen het hoofdversienummer in het URI-pad wordt weergegeven. Denk eraan dat een onderversienummer niet in het URI-pad is opgenomen. Deze strategie maakt gebruik van URI-routering om bepaalde API-versies te lokaliseren.

Voorbeeld: /verzend/v1/zendingen

Leidende beginselen van de strategie voor versiebeheer

We zijn van plan om minder hoofdversies voor FedEx-API's uit te brengen en hoofdversies twee jaar na de release van een nieuwere hoofdversie te laten verouderen. Als er bijvoorbeeld een hoofdversie 'N' wordt uitgebracht, zal de 'N-1'-versie twee jaar lang worden ondersteund vanaf het moment dat versie 'N' is uitgebracht.

Voorbeeld: In 2020 komt hoofdversie V1.0 uit. Als hoofdversie V2.0 in 2021 wordt uitgebracht, dan zal V1.0 in 2023 zijn verouderd.

Onderversies zullen vrijwel alle nieuwe functionaliteiten en functie-updates ondersteunen.

Voorbeeld: na hoofdversie 1.0 zullen onderversies 1.1, 1.2, etc. worden uitgebracht om nieuwe functionaliteit- en functie-updates te introduceren.

Alle eindpunten van een bepaalde API hebben op elk moment dezelfde hoofdversie. De nieuwste versie van de documentatie is alleen beschikbaar op het FedEx Developer Portal. Er zal echter een change log staan op de overzichtspagina van elke API, waarin de wijzigingen aan hoofd- en onderversies gedetailleerd worden weergegeven.

Wanneer worden de hoofdversies van de API uitgebracht?

We streven ernaar om het aantal hoofdversies voor onze API's tot een minimum te beperken. In bepaalde gevallen is een nieuwe hoofdversie echter onvermijdelijk. Hieronder volgen enkele belangrijke redenen voor het uitbrengen van een nieuwe hoofdversie:

• Als een bestaande lijstwaarde is verwijderd of als formaat of waarde zelf is veranderd in de aanvraag of als antwoord
  

  Voorbeeld: de lijstwaarde "GEOGRAPHIC_COORDINATES" voor het locationSearchCriterion-element wordt in de N-versie verwijderd; de datumindeling wordt van YY-MM-DD in MM-DD-YYYY gewijzigd; het locatietype wordt van FEDEX_ONSITE in ONSITE gewijzigd als reactie hierop.

• Als een bestaand element is verwijderd in de aanvraag of als antwoord
  

  Voorbeeld: het pickupType-element wordt verwijderd (of hernoemd) uit het verzoek om prijsopgave in de N-versie.

• Als een bestaande methode is verwijderd
  

  Voorbeeld: de methode om FedEx Express-tags aan te maken en te annuleren wordt niet langer ondersteund in de N-versie

• Als een bestaand element dat vroeger optioneel of voorwaardelijk was, verplicht is gesteld in de aanvraag
  

  Voorbeeld: het boekingsnummer is nu een verplicht element voor FedEx Express®-vrachtzendingen in de N-versie

• Als er wijzigingen in het API-ontwerp zijn
  

  Voorbeeld: de vraag- en antwoordstructuur is herschikt

• Als er wijzigingen in foutcodes en foutmeldingen zijn
  

  Voorbeeld: de foutcode wijzigen van INCORRECT.WEIGHT naar WEIGHT.LIMIT.EXCEEDED

Wanneer worden de onderversies van de API uitgebracht?

• Als er een nieuwe lijstwaarde is toegevoegd
  

  Voorbeeld: een nieuw transportaanbod is toegevoegd voor het serviceType-element in de N-versie

• Als er een nieuw element is toegevoegd
  

  Voorbeeld: een nieuw optioneel element om het telefoonnummer van de inklaringsagent voor internationale zendingen op te nemen

• Als er een nieuwe methode is toegevoegd
  

  Voorbeeld: een methode om internationale handelsdocumenten te wijzigen nadat ze zijn geüpload is toegevoegd in de N-versie.

• Als een bestaand element dat vroeger vereist was, optioneel is gemaakt
  

  Voorbeeld: een document-ID is nu optioneel omdat FedEx het documentatie-ID kan afleiden op basis van gebruikersinformatie.