La maggior parte delle applicazioni viene scritta utilizzando una forma di SDK client o, eventualmente, 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 apporterà modifiche alle nuove versioni dell'API. La tua applicazione non sarà interessata dalle modifiche apportate ad altre versioni dell'API finché non scegli di eseguire l'upgrade dell'SDK client (o di modificare l'URL API) per utilizzare la nuova versione dell'API Looker.
In che modo Looker apporta modifiche all'API
L'API Looker è progettata per fornire stabilità agli endpoint API di Looker e, di conseguenza, stabilità alle tue applicazioni.
Man mano che aggiungiamo altre 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 API, parametri e proprietà del tipo di risposta alla versione corrente dell'API Looker. Nella maggior parte dei casi, le aggiunte all'API non sono modifiche che causano interruzioni, 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 vengono visualizzati nelle release di Looker successive.
Per le modifiche all'API che interromperebbero il codice dell'applicazione esistente, raggruppiamo queste modifiche che causano interruzioni in una nuova versione dell'API. Ciò significa che la vecchia versione dell'API continuerà a funzionare come prima, mentre una nuova versione dell'API verrà eseguita contemporaneamente con le modifiche e gli aggiornamenti. In una singola istanza di Looker possono esistere più versioni dell'API in modo che tu possa scegliere quando eseguire l'upgrade alla nuova versione dell'API. Il codice esistente creato per chiamare il vecchio endpoint continuerà a chiamare il vecchio endpoint. Il nuovo codice deve chiamare la nuova versione dell'endpoint nel livello della versione API più recente.
Un'eccezione è rappresentata dai problemi di sicurezza critici. Se rileviamo un problema di sicurezza critico relativo a una parte specifica dell'API, faremo tutto il necessario per mitigare il problema di sicurezza il prima possibile, il che potrebbe includere la disattivazione della funzionalità vulnerabile fino a quando non sarà disponibile una soluzione adeguata.
Se dobbiamo ritirare una funzionalità, una funzione o una proprietà per fare spazio a un'implementazione o una soluzione migliore, in genere lasciamo l'API corrente così com'è, ma contrassegniamo gli endpoint API associati come "deprecati" per indicare che devi abbandonare l'endpoint nel codice dell'applicazione.
Modifiche che causano interruzioni e additive all'API
Una modifica che causa interruzioni è qualcosa che elimina o rinomina un artefatto esistente di un endpoint API. Potrebbe includere:
- Modifica o eliminazione del nome o del tipo di un parametro
- Aggiunta di un nuovo parametro obbligatorio
- Modifica dell'URL di base
- Modifica o eliminazione di una proprietà esistente in una risposta
Una modifica additiva, d'altra parte, può essere apportata agli endpoint stabili. Potrebbe includere:
- Nuovi parametri facoltativi
- Nuove proprietà nelle risposte (non consideriamo questa modifica che causa interruzioni perché presupponiamo che il codice ignori le proprietà sconosciute nelle risposte, una pratica comune nella community dell'API REST)
Se un endpoint API di Looker stabile richiede una modifica significativa per procedere con una nuova architettura o funzionalità, la modifica viene in genere aggiunta a un nuovo endpoint e raggruppata 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, il che significa che non è previsto che cambi. Looker non rilascerà modifiche che causano interruzioni agli 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 causano interruzioni. Quando utilizzi gli endpoint beta, valuta se una modifica all'API Looker potrebbe essere particolarmente dannosa per la tua app o per il ciclo di sviluppo. Se prevedi di utilizzare un endpoint beta, leggi le note di rilascio di Looker per essere a conoscenza di eventuali modifiche.
- Gli endpoint deprecati sono endpoint ancora supportati e utilizzabili al momento, ma verranno eliminati in una release futura. Il vecchio codice che utilizza un endpoint deprecato deve essere aggiornato per interrompere l'utilizzo dell'endpoint deprecato. Quando una release futura di Looker rimuove il supporto per l'endpoint, qualsiasi codice che lo utilizza ancora smetterà di funzionare. Nella maggior parte dei casi, un endpoint deprecato verrà sostituito da funzionalità migliorate. Se noti che la tua applicazione utilizza una funzione o una proprietà deprecata, ti consigliamo di eseguire 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 nel riferimento API 4.0. Gli endpoint non contrassegnati sono considerati stabili.
Tipi di chiamate API
I tipi di chiamate API definiti come chiamate API di query sono i seguenti:
- Chiamate necessarie per le pipeline di query automatiche
- Chiamate che recuperano i dati dal database client
- Chiamate che eseguono query SQL o recuperano i risultati per i contenuti
Ecco alcuni esempi:
I tipi di chiamate API definiti come chiamate API di amministrazione sono i seguenti:
- Chiamate necessarie per creare applicazioni, controllare i contenuti tra le istanze ed eseguire attività amministrative
- Chiamate che controllano l'istanza di Looker (Google Cloud Core)
- Chiamate che eseguono la gestione dei contenuti, la gestione delle autorizzazioni e degli utenti, l'amministrazione dell'istanza o l'estrazione dei contenuti tra le cartelle
Ecco alcuni esempi:
Eseguire la migrazione a una nuova versione dell'API
Quando scegli di eseguire l'upgrade dell'SDK client o dell'URL API a una nuova versione dell'API, dovrai esaminare il codice dell'applicazione per verificare se utilizzi qualcosa che è cambiato con la nuova versione dell'API. Assicurati di:
- Cercare nel codice dell'applicazione i nomi aggiornati di funzioni, valori e proprietà.
- Verificare che il codice dell'applicazione supporti eventuali modifiche ai tipi (ad esempio da intero a stringa).
- Eseguire un audit del codice (vedi la sezione Eseguire un audit del codice).
Eseguire un audit del codice
Per alcune lingue, le modifiche che causano interruzioni nell'API possono essere rilevate in fase di compilazione come errori di compilazione:
- Se la tua applicazione è scritta in un linguaggio compilato con tipi di dati statici, le modifiche strutturali ai tipi di parametri o di risposta in una nuova versione dell'API che sono in contrasto con il codice esistente dovrebbero essere facilmente visibili grazie al controllo dei tipi di compilazione e ai messaggi di errore del compilatore.
- Se la tua applicazione è scritta in un linguaggio dinamico con tipi di dati statici (ad esempio JavaScript, Ruby e Python), potrebbe essere più difficile individuare le parti dell'applicazione che saranno interessate dalle modifiche che causano interruzioni in una nuova versione dell'API. Questi tipi di linguaggi potrebbero richiedere test unitari di runtime per trovare eventuali problemi relativi alle modifiche dei tipi.
In tutti i casi, la best practice consiste nell'avere test unitari che esercitano il codice dell'applicazione, incluse le chiamate all'API Looker (non le chiamate simulate).