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.
Domande frequenti
Sarà necessario aggiornare l'URI all'ultima versione entro due anni cosicché FedEx potrà ritirare la versione più vecchia.
Le versioni minor vengono rilasciate per dare spazio a nuove caratteristiche e modifiche retrocompatibili e perciò non dovrebbero causare problemi alla vostra integrazione. Non è necessario effettuare l'aggiornamento alla nuova versione minor, ma è generalmente consigliato in quanto miglior pratica per aggiornare a versioni minor e sfruttare le nuove caratteristiche create per rispondere alle esigenze dei clienti.
Nei FedEx Web Services, ogni modifica richiede il rilascio di un nuovo WSDL o di una versione major, rendendo gli aggiornamenti più complessi per i clienti. Con le API FedEx, la maggior parte delle nuove caratteristiche può essere introdotta attraverso versioni minor, rendendo l'aggiornamento più semplice per i clienti. Ci saranno ulteriori versioni minor delle API e meno versioni major.
