La maggior parte delle applicazioni è scritta utilizzando una qualche forma di SDK client o magari un URL API. L'SDK client e gli URL API sono associati a una versione specifica dell'API Looker. La tua applicazione continuerà a funzionare anche se Looker apporta modifiche alle nuove versioni dell'API. L'applicazione non sarà interessata dalle modifiche nelle altre versioni dell'API finché non scegli di eseguire l'upgrade dell'SDK del client (o di modificare l'URL dell'API) per utilizzare la nuova versione dell'API Looker.
In che modo Looker apporta modifiche all'API
L'architettura di Looker è progettata per offrire stabilità per gli endpoint API Looker e, quindi, per le tue applicazioni.
Man mano che aggiungiamo nuove funzionalità a Looker, aggiorniamo anche l'API REST di Looker per accedere a queste nuove funzionalità o gestirle. Per ogni release di Looker, aggiungiamo nuove funzioni, parametri e proprietà dei tipi di risposta dell'API alla versione attuale dell'API Looker. Nella maggior parte dei casi, le aggiunte all'API non esportano le modifiche, quindi possiamo mantenere la versione esistente dell'API senza influire sul codice dell'applicazione esistente basato sull'API. Il codice dell'applicazione esistente potrebbe semplicemente non essere a conoscenza di nuove funzioni, parametri o funzionalità che compaiono nelle successive versioni di Looker.
Per le modifiche all'API che causerebbero errori nel codice dell'applicazione esistente, analizziamo queste modifiche in una nuova versione dell'API. Ciò significa che la vecchia versione dell'API continuerà a funzionare come prima, mentre con l'aggiunta di nuove modifiche e aggiornamenti verrà eseguita una nuova versione dell'API. Possono esistere più versioni API affiancate in una singola istanza di Looker, così potrai scegliere quando eseguire l'upgrade alla nuova versione dell'API. Il codice esistente, creato per chiamare il vecchio endpoint, continuerà a richiamare il vecchio endpoint. Il nuovo codice deve chiamare la nuova versione dell'endpoint nel livello di versione API più recente.
Un'eccezione è relativa ai problemi critici di sicurezza. Se rileviamo un problema di sicurezza critico relativo a una parte specifica dell'API, intraprenderemo tutte le azioni necessarie per mitigare il problema il prima possibile, e ciò potrebbe includere la disattivazione della funzionalità vulnerabile fino a quando non sarà disponibile una soluzione appropriata.
Se dobbiamo ritirare una funzionalità, una funzione o una proprietà per migliorare l'implementazione o la soluzione, di solito lasciamo l'API corrente, ma contrassegniamo gli endpoint API associati come "deprecato" per indicare che dovresti allontanarti dall'endpoint nel codice dell'applicazione.
Modifiche e modifiche cumulative all'API
Una interruzione è una modifica che elimina o rinomina un artefatto esistente di un endpoint API. Potrebbero essere inclusi:
- Modificare o eliminare il nome o il tipo di un parametro
- Aggiunta di un nuovo parametro obbligatorio
- Modificare l'URL di base
- Modificare o eliminare una proprietà esistente in una risposta
Una modifica additiva, invece, può essere apportata agli endpoint stabili. Tra questi:
- Nuovi parametri facoltativi
- Nuove proprietà nelle risposte (non consideriamo questa interruzione perché supponiamo che il tuo codice ignori le proprietà sconosciute nelle risposte, una pratica comune nella community dell'API REST)
Se un endpoint stabile dell'API Looker richiede una modifica significativa per procedere con la nuova architettura o funzionalità, in genere la modifica viene aggiunta a un nuovo endpoint e integrata in una nuova versione dell'API, in modo che l'endpoint API esistente rimanga invariato.
Flag per gli endpoint API
La maggior parte degli endpoint API è considerata stabile, ossia non è prevista una modifica. Looker non rilascerà modifiche che provocano errori negli endpoint stabili, tranne in casi estremi, ad esempio per risolvere un problema di sicurezza.
Altri endpoint API potrebbero essere contrassegnati come beta o deprecati:
- Gli endpoint beta sono in fase di sviluppo attivo e potrebbero cambiare in futuro. Non sono protetti dalle modifiche che provocano un errore. Quando utilizzi gli endpoint beta, valuta se una modifica all'API Looker avrà un impatto particolarmente significativo sulla tua app o sul tuo ciclo di sviluppo. Leggi le note di rilascio di Looker se prevedi di utilizzare un endpoint beta in modo da informarti di eventuali modifiche.
- Gli endpoint deprecati sono endpoint ancora supportati e al momento possono essere utilizzati, ma verranno eliminati in una release futura. Il codice precedente che utilizza un endpoint deprecato deve essere aggiornato per interrompere l'uso di questo endpoint. Quando una release futura di Looker rimuoverà il supporto per quell'endpoint, il codice che lo utilizza ancora non funzionerà. Nella maggior parte dei casi, un endpoint deprecato verrà sostituito da una funzionalità migliorata. Se ritieni che la tua applicazione utilizzi una funzione o una proprietà deprecata, è opportuno ripristinare il codice per sostituire l'elemento deprecato il prima possibile.
Gli endpoint beta e deprecati sono contrassegnati come tali nel riferimento API. Gli endpoint non contrassegnati sono considerati stabili.
Eseguire la migrazione a una nuova versione dell'API
Quando scegli di eseguire l'upgrade dell'SDK client o dell'URL dell'API a una nuova versione dell'API, devi controllare il codice dell'applicazione per verificare se ti affidi a qualcosa che è cambiato con la nuova versione dell'API. Assicurati di:
- Cerca nel codice dell'applicazione la funzione, il valore e i nomi delle proprietà aggiornati.
- Verifica che il codice dell'applicazione supporti eventuali modifiche ai tipi (ad esempio intero da stringa a stringa).
- Controlla il codice (vedi la sezione di seguito).
Controllo del codice
Per alcuni linguaggi, le modifiche che provocano errori nell'API possono essere rilevate al momento della creazione come errori di compilazione:
- Se la tua applicazione è scritta in un linguaggio compilato e altamente digitato, le modifiche strutturali ai parametri o ai tipi di risposta in una nuova versione dell'API in contrasto con il tuo codice esistente dovrebbero essere facilmente evidenti grazie al controllo del tipo di compilazione e ai messaggi di errore del compilatore.
- Se la tua applicazione è scritta in un linguaggio dinamico di tipo generico (come JavaScript, Ruby e Python), potrebbe essere più difficile individuare le parti dell'applicazione che saranno interessate dall'interruzione delle modifiche in una nuova versione dell'API. Per alcuni tipi di lingue potrebbero essere necessari test delle unità di runtime per individuare eventuali problemi relativi ai cambiamenti nei tipi.
In ogni caso, la best practice prevede di eseguire test delle unità che esercitano il codice dell'applicazione, comprese le chiamate all'API Looker (non le chiamate fittizie).