FedEx API – Versionsmanagement

Wir verwalten bei FedEx API-Versionen mit semantischer Versionierung. Jede Version wird im Format Major.Minor dargestellt (z. B. Ship API 1.1). Eine neue Major-Version bedeutet, dass die Änderungen nicht abwärtskompatibel sind, im Gegensatz zu Änderungen von Minor-Versionen.

Bei FedEx wird eine einfache URI-Versionierung verwendet. Daher wird im URI-Pfad nur die Major-Versionsnummer angegeben. Minor-Versionsnummern werden nicht im URI-Pfad angegeben. Bestimmte Versionen der API werden mithilfe von URI-Weiterleitung identifiziert.

Beispiel: /ship/v1/shipments

Leitlinien für das Versionsmanagement

In Zukunft sollen seltener Major-Versionen für FedEx APIs veröffentlicht und zwei Jahre nach ihrer Veröffentlichung für ungültig erklärt. Nach der Veröffentlichung der Major-Version „N“ wird beispielsweise die Version „N-1“ zwei Jahre lang unterstützt.

Beispiel: 2020 wird die Major-Version V1.0 veröffentlicht. Wird 2021 die Major-Version V2.0 veröffentlicht, erfolgt 2023 die Einstellung von V1.0.

Minor-Versionen unterstützen die meisten neuen Funktionen und aktualisierten Features.

Beispiel: Im Anschluss an Major-Version 1.0 werden die Minor-Versionen 1.1, 1.2 usw. veröffentlicht, um neue Funktionen und aktualisierte Features zu implementieren.

Die Endpunkte einer bestimmten API müssen zu jeder Zeit dieselbe Major-Versionsnummer aufweisen. Die aktuelle Version der Dokumentation steht nur im FedEx Developer Portal zur Verfügung. Allerdings werden auf jeder Übersichtsseite einer API in einem Änderungsprotokoll die einzelnen Änderungen der Major- und Minor-Versionen aufgeführt.

Wann werden Major-Versionen von APIs veröffentlicht?

Wir möchten die Anzahl an Major-Versionen für unsere APIs reduzieren. In einigen Fällen sind neue Major-Versionen jedoch nicht zu vermeiden. Folgende wichtige Gründe können die Veröffentlichung einer neuen Major-Version erforderlich machen:

• Wenn ein vorhandener Aufzählungswert entfernt wird oder sich Format oder Wert bei einer Anfrage oder Antwort geändert haben
  

  Beispiel: Der Aufzählungswert „GEOGRAPHIC_COORDINATES“ für das locationSearchCriterion-Element wird aus Version N entfernt. Die Datumssyntax wird von JJ-MM-TT in MM-TT-JJJJ geändert. Der Ortstyp FEDEX_ONSITE wird entsprechend in ONSITE geändert.

• Wenn ein vorhandenes Element bei einer Anfrage oder Antwort entfernt wird
  

  Beispiel: Das pickupType-Element wird in Version N aus Tarifanfragen entfernt (oder umbenannt).

• Wenn eine vorhandene Methode entfernt wird
  

  Beispiel: Die Methode zum Erstellen und Verwerfen von FedEx Express Tags wird in Version N nicht mehr unterstützt

• Wenn ein vorhandenes optionales oder bedingtes Element in der Anfrage als obligatorisch festgelegt wird
  

  Beispiel: Die Buchungsnummer ist nun in Version N ein erforderliches Element für FedEx Express® Freight Sendungen

• Wenn Änderungen am API-Design vorgenommen werden
  

  Beispiel: Die Struktur von Anfragen und Antworten wurde geändert

• Wenn Änderungen an Fehlercodes und Fehlermeldungen vorgenommen werden
  

  Beispiel: Der Fehlercode INCORRECT.WEIGHT wird zu WEIGHT.LIMIT.EXCEEDED geändert

Wann werden Minor-Versionen von APIs veröffentlicht?

• Wenn ein neuer Aufzählungswert hinzugefügt wird
  

  Beispiel: Ein neues Transportangebot wird für das serviceType-Element in Version N hinzugefügt

• Wenn ein neues Element hinzugefügt wird
  

  Beispiel: Ein neues optionales Element zum Einfügen der Telefonnummer des Zollagenten für internationale Sendungen wird hinzugefügt

• Wenn eine neue Methode hinzugefügt wird
  

  Beispiel: In Version N wurde eine Methode zum Bearbeiten internationaler Handelsdokumente nach ihrem Upload hinzugefügt.

• Wenn ein vorhandenes obligatorisches Element als optional festgelegt wird
  

  Beispiel: Die Dokumenten-ID ist jetzt optional. FedEx kann diese Kennung aus den Benutzerdaten herleiten.