La maggior parte delle applicazioni è scritta utilizzando una qualche forma di SDK client o, eventualmente, un URL API. Gli URL dell'SDK client e dell'API sono associati a una versione specifica dell'API Looker. La tua applicazione continuerà a funzionare anche quando Looker apporta modifiche alle nuove versioni dell'API. La tua applicazione non sarà interessata dalle modifiche in altre versioni dell'API finché non sceglierai 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 garantire la stabilità degli endpoint API Looker e, di conseguenza, la stabilità delle tue applicazioni.
Man mano che aggiungiamo funzionalità e capacità a Looker, aggiorniamo anche l'API REST di Looker per accedere o gestire queste nuove funzionalità. Per ogni release di Looker, aggiungiamo nuove funzioni, parametri e proprietà di tipo di risposta dell'API alla versione corrente dell'API Looker. Nella maggior parte dei casi, le aggiunte all'API non sono modifiche incompatibili, 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 successive di Looker.
Le modifiche all'API che potrebbero causare errori nel codice dell'applicazione esistente vengono raggruppate 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 con le modifiche e gli aggiornamenti. Più versioni dell'API possono coesistere in una singola istanza di Looker, in modo da poter 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 di versione dell'API più recente.
Fanno eccezione i 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 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, di solito lasciamo l'API attuale così com'è, ma contrassegniamo gli endpoint API associati come "deprecated" per indicare che devi passare a un altro endpoint nel codice dell'applicazione.
Modifiche non compatibili e additive all'API
Una modifica in violazione è un'operazione che elimina o rinomina un elemento 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
- Modifica dell'URL di base
- Modificare o eliminare una proprietà esistente in una risposta
Una modifica additiva, invece, può essere apportata agli endpoint stabili. ad esempio:
- Nuovi parametri facoltativi
- Nuove proprietà nelle risposte (non consideriamo questa modifica una rottura perché presupponiamo che il codice ignori le proprietà sconosciute nelle risposte, come è prassi comune nella community delle API REST)
Se un endpoint API Looker stabile richiede una modifica significativa per procedere con una nuova architettura o funzionalità, la modifica viene solitamente aggiunta a un nuovo endpoint e raggruppata in una nuova versione dell'API in modo che l'endpoint API esistente rimanga invariato.
Indicatori per gli endpoint API
La maggior parte degli endpoint API è considerata stabile, il che significa che non dovrebbero cambiare. Looker non rilascia modifiche incompatibili per gli 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 dalle modifiche che causano interruzioni. Quando utilizzi 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 ritirati sono endpoint ancora supportati e possono essere utilizzati al momento, ma verranno eliminati in una release futura. Il codice precedente che utilizza un endpoint deprecato deve essere aggiornato per non utilizzarlo più. Quando una release futura di Looker rimuoverà il supporto per quell'endpoint, qualsiasi codice che lo utilizza ancora non funzionerà più. Nella maggior parte dei casi, un endpoint deprecato 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 all'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 API a una nuova versione dell'API, devi esaminare il codice dell'applicazione per verificare se utilizzi elementi che sono cambiati con la nuova versione dell'API. Assicurati di svolgere le seguenti operazioni:
- Cerca nel codice dell'applicazione i nomi aggiornati di funzione, valore e proprietà.
- Verifica che il codice dell'applicazione supporti eventuali modifiche ai tipi (ad esempio da intero a stringa).
- Controlla il codice (consulta la sezione Controllo del codice).
Controllo del codice
Per alcune lingue, le modifiche non compatibili nell'API possono essere rilevate in fase di compilazione come errori di compilazione:
- Se la tua applicazione è scritta in un linguaggio compilato con tipi fortemente definiti, le modifiche strutturali ai tipi di parametri o di risposta in una nuova versione dell'API che sono in conflitto con il codice esistente dovrebbero essere subito evidenti grazie al controllo del tipo di compilazione e ai messaggi di errore del compilatore.
- Se la tua applicazione è scritta in un linguaggio dinamico con tipi labili (come JavaScript, Ruby e Python), potrebbe essere più difficile individuare le parti dell'applicazione che saranno interessate dalle modifiche che comportano interruzioni in una nuova versione dell'API. Questi tipi di linguaggi potrebbero richiedere test di unità di runtime per rilevare eventuali problemi relativi alle modifiche dei tipi.
In ogni caso, la best practice è avere test di unità che eseguono il codice dell'applicazione, incluse le chiamate all'API Looker (non chiamate simulate).