La maggior parte delle applicazioni è scritta utilizzando una forma di SDK client o un URL API. L'SDK del client e gli URL dell'API sono associati a una versione specifica dell'API Looker. L'applicazione continuerà a funzionare anche se Looker apporta modifiche alle nuove versioni dell'API. La tua applicazione non sarà interessata dalle modifiche in altre versioni dell'API finché non scegli di eseguire l'upgrade dell'SDK 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'API Looker è progettata per fornire stabilità per gli endpoint API Looker e quindi per le tue applicazioni.
Man mano che aggiungiamo altre caratteristiche e 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 proprietà API, parametri e tipi di risposta alla versione corrente dell'API Looker. Nella maggior parte dei casi, le aggiunte all'API non compromettono le modifiche, pertanto 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 conoscere nuove funzioni, parametri o funzionalità visualizzati nelle release successive di Looker.
Per le modifiche all'API che danneggiano il codice dell'applicazione esistente, queste modifiche vengono raggruppate in una nuova versione dell'API. Ciò significa che la vecchia versione dell'API continuerà a funzionare come prima, mentre in combinazione con una nuova versione dell'API e le modifiche e gli aggiornamenti. Più versioni API possono esistere fianco a fianco in una singola istanza Looker per consentirti di scegliere quando eseguire l'upgrade alla nuova versione dell'API. Il codice esistente che è stato creato per chiamare il vecchio endpoint continuerà a chiamare quello precedente. Il nuovo codice deve chiamare la nuova versione dell'endpoint nel livello di versione API più recente.
Un'unica eccezione è per i problemi di sicurezza critici. Se rileviamo un problema di sicurezza critico relativo a una determinata parte dell'API, faremo il possibile per mitigare il prima possibile il problema di sicurezza, inclusa la disattivazione della funzionalità vulnerabile finché non sarà disponibile una soluzione appropriata.
Se dobbiamo ritirare una funzionalità, una funzione o una proprietà per rendere disponibile un'implementazione o una soluzione migliori, di solito lasciamo l'API corrente così com'è, ma contrassegniamo gli endpoint API associati come "deprecato" per indicare che dovresti allontanarti dall'endpoint nel codice dell'applicazione.
Modifiche che provocano errori e additive all'API
Una modifica che provoca errori è un elemento che elimina o rinomina un artefatto esistente di un endpoint API. Potrebbero essere incluse:
- Modificare o eliminare il nome o il tipo di un parametro
- Aggiunta di un nuovo parametro richiesto
- Modificare l'URL di base
- Modificare o eliminare una proprietà esistente in una risposta
Una modifica additiva, invece, può essere apportata agli endpoint stabili. Potrebbero includere:
- 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 API stabile ha bisogno di 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 API, in modo che l'endpoint API esistente rimanga invariato.
Flag per gli endpoint API
La maggior parte degli endpoint API è considerata stabile, il che significa che non sono previste modifiche. Looker non rilascia modifiche che provocano errori per gli endpoint stabili, tranne che 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 da modifiche che provocano errori. Quando utilizzi gli endpoint beta, valuta se una modifica all'API Looker causerebbe particolarmente problemi alla tua app o al tuo ciclo di sviluppo. Leggi le note di rilascio di Looker se prevedi di utilizzare un endpoint beta per informarti di eventuali modifiche.
- Gli endpoint deprecati sono endpoint che sono ancora supportati e possono essere ancora utilizzati al momento, ma verranno eliminati in una release futura. Il codice precedente che utilizza un endpoint deprecato deve essere aggiornato per interromperne l'utilizzo. Quando una release futura di Looker rimuove il supporto per tale endpoint, qualsiasi codice che lo utilizza ancora non funziona. Nella maggior parte dei casi, un endpoint deprecato verrà sostituito da una funzionalità migliorata. Se ritieni che l'applicazione utilizzi una funzione o una proprietà deprecate, è opportuno eseguire di nuovo il refactoring del codice per sostituire l'elemento deprecato il prima possibile.
Gli endpoint beta e deprecati sono contrassegnati come tali in Explorer API e nei riferimenti per le API 4.0. Gli endpoint non contrassegnati sono considerati stabili.
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 vedere se ti affidi a qualcosa che è cambiato nella nuova versione dell'API. Procedi nel seguente modo:
- Cerca nel codice dell'applicazione la funzione, il valore e i nomi delle proprietà aggiornati.
- Verifica che il codice dell'applicazione supporti tutte le modifiche ai tipi (ad esempio da numero intero a stringa).
- Controlla il codice (consulta 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 strettamente digitato, le modifiche strutturali ai parametri o ai tipi di risposta in una nuova versione dell'API che sono in contrasto con il tuo codice esistente dovrebbero essere facilmente evidenti grazie ai messaggi di errore di compilazione e controllo del tipo di compilazione.
- Se la tua applicazione è scritta in un linguaggio dinamico, 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. Questi tipi di linguaggi potrebbero richiedere test delle unità di runtime per trovare eventuali problemi relativi ai cambiamenti nei tipi.
In ogni caso, la best practice è eseguire test delle unità che esercitano il codice dell'applicazione, comprese le chiamate all'API Looker (non le chiamate fittizie).