Cambiare versione API tenendo conto dei flussi di dati
Nel cambio di API, chiamanti, significato dei dati e risposte devono essere coerenti. Un caso concreto rende verificabile la migrazione.
Pianifichi il cambio di un’interfaccia di programmazione delle applicazioni (API) a partire dai flussi di dati interessati. Il nuovo endpoint è solo una parte della migrazione: anche campi, autorizzazioni e interpretazione delle risposte devono essere adatti al sistema chiamante.
Individuare i chiamanti interessati
In un’azienda fittizia un portale clienti e un’importazione notturna inviano ordini alla stessa API. Migrare soltanto il portale lascerebbe indietro il secondo chiamante. Annoti quali funzioni usa ciascun chiamante e chi può eseguirne la migrazione. Utilizzi le informazioni sulle modifiche e sulla dismissione del fornitore effettivo; un numero di versione non stabilisce una scadenza di migrazione universale.
Google AIP-180 distingue la compatibilità del codice sorgente, della trasmissione e della semantica. La guida aiuta a valutare le modifiche; non garantisce il comportamento di qualsiasi API di terzi.
Descrivere la modifica con un esempio svolto
Nel nostro esempio la vecchia richiesta contiene testo nel campo delivery_note. La nuova versione attende il testo sotto delivery_note.text. Entrambe devono trasmettere la stessa istruzione di consegna: «Tor B». Sostituire un URL o stabilire una connessione non basta quindi per la migrazione.
Verifica | Decisione nell’esempio |
|---|---|
Che cosa va conservato? | Istruzione di consegna Tor B sull’ordine corretto |
Che cosa cambia tecnicamente? | Il campo di testo passa a una struttura annidata |
Che cosa vale come successo? | L’ordine di destinazione contiene l’istruzione invariata |
Che fare se manca il testo? | Creare l’ordine senza istruzione di consegna, come prima |
Verifichi anche come vengono segnalati gli errori e l’elaborazione ancora in corso. Una struttura di risposta diversa può incidere sul chiamante anche se la richiesta continua a essere accettata.
Confrontare vecchio e nuovo nelle stesse condizioni
In un ambiente di test adatto prepari un ordine normale e un caso senza istruzione di consegna. Confronti i dati salvati a destinazione e la risposta visibile. Chiarisca inoltre se i diritti di accesso utilizzati coprono entrambe le versioni. Per questo confronto non si devono inviare ordini reali lungo due percorsi di produzione.
Coordinare il passaggio con le operazioni aperte
Definisca da quale punto le nuove richieste usano il nuovo percorso. Le richieste già inviate ma non ancora confermate necessitano di una corrispondenza affinché una ripetizione non venga trattata come un nuovo ordine. Concordi un ritorno al vecchio percorso per le nuove richieste e verifichi separatamente che cosa accade ai dati già scritti. Ripristinare un URL non annulla queste modifiche.
La vecchia versione può essere rimossa da questo flusso quando tutti i chiamanti censiti sono migrati e le operazioni aperte hanno una corrispondenza. Documenti lo stato effettivamente verificato oltre alla nuova etichetta di versione.
Fonti
Continuate a leggere
Tutti gli articoli
API & integrazione con ASES
ERP, CRM e negozio online collegati in modo pulito