La maggior parte delle applicazioni viene scritta utilizzando una qualche forma di SDK client o, eventualmente, un URL API. Gli URL dell'API e dell'SDK client 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 dell'API) per utilizzare la nuova versione dell'API Looker.
Come Looker apporta modifiche all'API
L'API Looker è progettata per garantire la stabilità degli endpoint API Looker e, di conseguenza, la stabilità delle tue applicazioni.
Man mano che aggiungiamo 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à del tipo di risposta dell'API Looker alla versione corrente. 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 conoscere nuove funzioni, parametri o funzionalità che vengono visualizzati nelle versioni successive di Looker.
Per le modifiche all'API che interromperebbero il codice dell'applicazione esistente, raggruppiamo queste modifiche che provocano errori 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 in parallelo 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 chiamarlo. 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 scopriamo un problema di sicurezza critico relativo a una parte specifica dell'API, faremo tutto il necessario per mitigarlo il prima possibile, il che potrebbe includere la disattivazione della funzionalità vulnerabile finché 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 "obsoleti" per indicare che devi abbandonare l'endpoint nel codice dell'applicazione.
Modifiche additive e che causano interruzioni 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, invece, può essere apportata agli endpoint stabili. Possono includere:
- Nuovi parametri facoltativi
- Nuove proprietà nelle risposte (non lo consideriamo un cambiamento che causa interruzioni perché presupponiamo che il tuo codice ignori le proprietà sconosciute nelle risposte, il che è una pratica comune nella community delle 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 cambino. 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 obsoleti:
- Gli endpoint beta sono in fase di sviluppo attivo e potrebbero cambiare in futuro. Non sono protette da 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 il tuo 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 ritirati sono endpoint ancora supportati e utilizzabili al momento, ma che verranno eliminati in una release futura. Il codice precedente che utilizza un endpoint ritirato deve essere aggiornato per interrompere l'utilizzo dell'endpoint ritirato. Quando una release futura di Looker rimuoverà il supporto per questo endpoint, qualsiasi codice che lo utilizza ancora non funzionerà più. Nella maggior parte dei casi, un endpoint ritirato verrà sostituito da una funzionalità migliorata. Se scopri che la tua applicazione utilizza una funzione o una proprietà ritirata, ti consigliamo di eseguire il refactoring del codice per sostituire l'elemento ritirato il prima possibile.
Gli endpoint beta e ritirati 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 automatizzate
- Chiamate che recuperano i dati dal database client
- Chiamate che eseguono query SQL o recuperano risultati per i contenuti
Alcuni esempi sono:
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, delle autorizzazioni e degli utenti, l'amministrazione delle istanze o l'estrazione dei contenuti da più cartelle
Ecco alcuni esempi:
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, devi esaminare il codice dell'applicazione per verificare se utilizzi qualcosa che è cambiato con la nuova versione dell'API. Assicurati di svolgere le seguenti operazioni:
- Cerca nel codice dell'applicazione i nomi aggiornati di funzioni, valori e proprietà.
- Verifica che il codice dell'applicazione supporti eventuali modifiche ai tipi (ad esempio da numero intero a stringa).
- Controlla il codice (vedi la sezione Controllo del codice).
Controllo 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 e fortemente tipizzato, 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 evidenti grazie al controllo del tipo di compilazione e ai messaggi di errore del compilatore.
- Se la tua applicazione è scritta in un linguaggio dinamico a tipizzazione debole (come JavaScript, Ruby e Python), potrebbe essere più difficile individuare le parti dell'applicazione che saranno interessate da modifiche che causano interruzioni in una nuova versione dell'API. Questi tipi di linguaggi potrebbero richiedere test delle unità in fase di runtime per trovare eventuali problemi relativi alle modifiche ai tipi.
In tutti i casi, la best practice consiste nell'avere unit test che esercitano il codice dell'applicazione, incluse le chiamate all'API Looker (non chiamate simulate).