La maggior parte delle applicazioni viene scritta utilizzando una qualche forma di SDK client o possibilmente un URL API. L'SDK 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. Le modifiche apportate ad altre versioni dell'API non saranno interessate dalla tua applicazione 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 è stata progettata per offrire stabilità agli endpoint dell'API Looker e quindi a stabilità per le applicazioni.
Man mano che aggiungiamo altre funzionalità a Looker, aggiorniamo anche l'API REST 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 provocano l'interruzione, 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 delle nuove funzioni, parametri o caratteristiche che compaiono nelle release successive di Looker.
Le modifiche all'API che danneggiano il codice dell'applicazione esistente vengono raggruppate in una nuova versione dell'API. Ciò significa che la versione precedente dell'API continuerà a funzionare come prima, mentre una nuova versione dell'API viene eseguita insieme alle modifiche e agli aggiornamenti. Possono esistere più versioni dell'API affiancate in una singola istanza di Looker, così puoi scegliere quando eseguire l'upgrade alla nuova versione dell'API. Il codice esistente creato per chiamare l'endpoint precedente continuerà a chiamare quello precedente. Il nuovo codice deve chiamare la nuova versione dell'endpoint nel livello di versione API più recente.
Fanno eccezione i problemi di sicurezza critici. Se rileviamo un problema di sicurezza critico relativo a una determinata parte dell'API, intraprenderemo quanto necessario per mitigare il problema in questione nel più breve tempo possibile, ad esempio disattivando la funzionalità vulnerabile fino a quando non sarà disponibile una soluzione adeguata.
Se dobbiamo ritirare una funzionalità, una funzione o una proprietà per far posto a un'implementazione o una soluzione migliore, di solito non lasciamo l'API attuale così com'è, ma contrassegniamo gli endpoint API associati come "deprecati" per indicare che devi allontanarti dall'endpoint nel codice dell'applicazione.
Interruzione e modifiche cumulative all'API
Una modifica interruzione è qualcosa che elimina o rinomina un artefatto esistente di un endpoint API. Potrebbero essere inclusi:
- Modifica o eliminazione del nome o del tipo di 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. Ecco alcuni esempi:
- Nuovi parametri facoltativi
- Nuove proprietà nelle risposte (non consideriamo questa interruzione perché presupponiamo che il tuo codice ignorerà le proprietà sconosciute nelle risposte, una pratica comune nella community delle API REST)
Se un endpoint stabile dell'API Looker ha bisogno di una modifica significativa per procedere con una nuova architettura o funzionalità, di solito 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 endpoint API
La maggior parte degli endpoint API sono considerati stabili, il che significa che non sono previsti cambiamenti. Looker non rilascerà modifiche che provocano un errore agli endpoint stabili, se non in casi estremi, come la correzione di 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 protetti da modifiche che provocano un errore. Quando utilizzi gli endpoint beta, valuta se una modifica all'API Looker potrebbe compromettere il funzionamento della tua app o del tuo ciclo di sviluppo. Leggi le note di rilascio di Looker se prevedi di utilizzare un endpoint beta per essere a conoscenza di eventuali modifiche.
- Gli endpoint deprecati sono endpoint ancora supportati e utilizzabili al momento, ma che verranno eliminati in una release futura. Il codice precedente che utilizza un endpoint deprecato deve essere aggiornato in modo da non utilizzare più l'endpoint deprecato. Quando una release futura di Looker rimuoverà il supporto per quell'endpoint, qualsiasi codice che lo sta ancora utilizzando non funzionerà. 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 effettuare 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.
Migrazione a una nuova versione dell'API
Se scegli di eseguire l'upgrade dell'SDK del client o dell'URL dell'API a una nuova versione dell'API, dovrai esaminare il codice dell'applicazione per verificare se fai affidamento su qualcosa che è cambiato con la nuova versione dell'API. Assicurati di:
- Cerca nel codice dell'applicazione i nomi di funzione, valore e proprietà aggiornati.
- Verifica che il codice dell'applicazione supporti le modifiche di tipo (ad esempio da numero intero a stringa).
- Controlla il tuo codice (vedi la sezione di seguito).
Controllo del codice
Per alcuni linguaggi, le modifiche che provocano un errore nell'API possono essere rilevate al momento della creazione sotto forma di errori di compilazione:
- Se la tua applicazione è scritta in un linguaggio compilato e di forte tipo, le modifiche strutturali ai tipi di parametri o risposte in una nuova versione dell'API che sono in contrasto con il tuo codice esistente dovrebbero essere immediatamente 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 basso tipo di digitazione (ad esempio JavaScript, Ruby e Python), potrebbe essere più difficile individuare le parti dell'applicazione che saranno interessate dalle modifiche che provocano un errore in una nuova versione dell'API. Questi tipi di linguaggi potrebbero richiedere test delle unità di runtime per individuare eventuali problemi relativi alle modifiche ai tipi.
In tutti i casi, è consigliabile eseguire test delle unità che esercitino il codice dell'applicazione, incluse le chiamate all'API Looker (non le chiamate simulate).