Versionamento API FedEx

In FedEx, ci serviamo del versionamento semantico per gestire le versioni delle API. Ogni versione è rappresentata dal formato versione major.minor (ad esempio, API Spedizione 1.1). Una nuova versione major indica che la modifica non è retrocompatibile, mentre una nuova versione minor indica la presenza di una modifica retrocompatibile.

In FedEx, seguiamo il versionamento URI semplice. Ciò comporta che solo il numero di versione major è rappresentato nel percorso dell'URI. Nota: il numero di versione minor non è incluso nel percorso dell'URI. Questa strategia si serve dell'instradamento dell'URI per individuare versioni particolari dell'API.

Esempio: /spedizione/v1/spedizioni

Principi cardine della strategia di versionamento

Abbiamo in programma di rilasciare meno versioni major per le API FedEx e disattivare una versione major dopo due anni dal rilascio di una versione major più recente. Ad esempio, se una versione major ‘N’ viene rilasciata, la versione ‘N-1’ sarà supportata per i due anni successivi al rilascio della versione ‘N.’

Esempio: Nel 2020, viene rilasciata la versione V1.0. Se nel 2021 viene rilasciata la versione V2.0, la V1.0 verrà disattivata nel 2023.

Le versioni minor supporteranno la maggior parte dei nuovi aggiornamenti di funzionalità e caratteristiche..

Esempio: Dopo la versione major 1.0, le versioni minor 1.1, 1.2, etc. verranno rilasciate per introdurre nuovi aggiornamenti di funzionalità e caratteristiche.

In qualsiasi momento, tutti i terminali per una particolare API avranno la stessa versione major. L'ultima versione della documentazione sarà disponibile solo nel FedEx Developer Portal. Ci sarà tuttavia un registro modifiche sotto ogni pagina di riepilogo dell'API che illustrerà nel dettaglio le modifiche alle versioni major e minor.

Quando vengono rilasciate le versioni major delle API?

Stiamo cercando di ridurre al minimo il numero di versioni major per le nostre API. Tuttavia, in alcuni casi è inevitabile una nuova versione major. Di seguito alcuni dei motivi principali che spingono al rilascio di una nuova versione major:

• Quando un valore di enumerazione esistente viene rimosso o il formato o il valore cambia nella risposta o nella richiesta
  

  Esempio: Il valore di enumerazione “GEOGRAPHIC_COORDINATES” per l'elemento locationSearchCriterion viene rimosso nella versione N; la sintassi della data cambia da AA-MM-GG a MM-GG-AAAA; in risposta, viene modificato il tipo di località da FEDEX_ONSITE a ONSITE

• Quando un elemento esistente viene rimosso nella risposta o nella richiesta
  

  Esempio: l'elemento pickupType è rimosso (o rinominato) dalla richiesta di tariffa nella versione N

• Quando un metodo esistente viene rimosso
  

  Esempio: Il metodo per creare ed eliminare tag FedEx Express non è più supportato nella versione N

• Quando un elemento esistente che era solitamente opzionale o condizionale è reso obbligatorio nella richiesta
  

  Esempio: Il numero di prenotazione è ora un elemento obbligatorio per le spedizioni FedEx Express® Freight nella versione N

• Quando ci sono modifiche alla progettazione dell'API
  

  Esempio: La struttura di richiesta e risposta è riorganizzata

• Quando ci sono modifiche con codici e messaggi di errore
  

  Esempio: Modifica al codice di errore da INCORRECT.WEIGHT a WEIGHT.LIMIT.EXCEEDED

Quando vengono rilasciate le versioni minor delle API?

• Quando viene aggiunto un nuovo valore di enumerazione
  

  Esempio: Una nuova offerta di trasporto è aggiunta per l'elemento Tipo di servizio nella versione N

• Quando viene aggiunto un nuovo elemento
  

  Esempio: Un nuovo elemento opzionale per includere il numero telefonico del broker per le spedizioni internazionali

• Quando viene aggiunto un nuovo metodo
  

  Esempio: Un metodo per modificare i documenti commerciali internazionali dopo che vengono caricati è aggiunto nella versione N.

• Quando diventa opzionale un elemento esistente che solitamente era obbligatorio
  

  Esempio: L'ID documento è ora opzionale perché FedEx può ricavare l'ID documentazione sulla base delle informazioni utente.