La maggior parte delle applicazioni è scritta utilizzando una forma di SDK client o possibilmente un URL API. Gli URL SDK e API del client 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 nelle altre versioni dell'API finché non sceglierai 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 offrire stabilità per gli endpoint API Looker e, quindi, per le tue applicazioni.
Man mano che aggiungiamo nuove funzionalità 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 funzioni API, parametri e proprietà dei tipi di risposta alla versione corrente dell'API Looker. Nella maggior parte dei casi, le aggiunte all'API non intervengono le modifiche, 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à visualizzati nelle versioni successive di Looker.
Per le modifiche all'API che potrebbero causare l'interruzione del 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 con la nuova versione dell'API verrà eseguita la modifica e l'aggiornamento. Possono esistere più versioni dell'API affiancate in una singola istanza di Looker, quindi puoi scegliere quando eseguire l'upgrade alla nuova versione dell'API. Il codice esistente che è stato creato per chiamare il vecchio endpoint continuerà a richiamare quello precedente. Il nuovo codice deve chiamare la nuova versione dell'endpoint nel livello di versione API più recente.
Un'eccezione è rappresentata dai problemi critici di sicurezza. Se rileviamo un problema di sicurezza critico relativo a una parte specifica dell'API, faremo il possibile per mitigare il prima possibile il problema di sicurezza, che potrebbe includere la disattivazione della funzionalità vulnerabile fino a quando non sarà disponibile una soluzione appropriata.
Se dobbiamo ritirare una funzionalità, una funzione o una proprietà per migliorare l'implementazione o la soluzione, in genere lasciamo l'API corrente così com'è, ma contrassegniamo gli endpoint API associati come "deprecated" per indicare che dovresti allontanarti dall'endpoint nel codice dell'applicazione.
Modifiche che provocano errori e additivi all'API
Una modifica che esegue un errore è un elemento che elimina o rinomina un artefatto esistente di un endpoint API. Ad esempio:
- 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
D'altra parte, è possibile apportare una modifica additiva agli endpoint stabili. Potrebbero includere:
- Nuovi parametri facoltativi
- Nuove proprietà nelle risposte (non consideriamo questa interruzione perché supponiamo che il tuo codice ignorerà le proprietà sconosciute nelle risposte, una pratica comune nella community di API REST)
Se un endpoint stabile dell'API Looker richiede 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 dell'API, in modo che l'endpoint API esistente rimanga invariato.
Flag per gli endpoint API
La maggior parte degli endpoint API è considerata stabile, ossia non è previsto che vengano modificati. Looker non rilascerà modifiche che provocano errori negli endpoint stabili, ad eccezione dei casi estremi, ad esempio per risolvere un problema di sicurezza.
Altri endpoint API potrebbero essere contrassegnati come beta o ritirati:
- 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 avrà un impatto particolarmente significativo sulla tua app o sul tuo ciclo di sviluppo. Leggi le note di rilascio di Looker se prevedi di utilizzare un endpoint beta in modo da essere a conoscenza 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. Per interrompere l'uso dell'endpoint deprecato, il codice precedente che utilizza un endpoint deprecato dovrebbe essere aggiornato. Quando una release futura di Looker rimuove il supporto per quell'endpoint, qualsiasi codice che lo utilizza ancora non funzionerà. Nella maggior parte dei casi, un endpoint deprecato verrà sostituito da una funzionalità migliorata. Se ritieni che la tua applicazione stia utilizzando una funzione o una proprietà deprecata, è consigliabile refactoring del codice per sostituire l'elemento deprecato il prima possibile.
Gli endpoint beta e deprecati sono contrassegnati come tali in Explorer API e nella sezione Riferimento API 4.0. Gli endpoint che non sono contrassegnati sono considerati stabili.
Eseguire la migrazione a una nuova versione dell'API
Quando scegli di eseguire l'upgrade dell'SDK del client o dell'URL dell'API a una nuova versione dell'API, dovrai rivedere il codice dell'applicazione per vedere se ti affidi a un aspetto che è cambiato con la 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 eventuali modifiche dei tipi (ad esempio il numero intero dalla 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 build come errori di compilazione:
- Se la tua applicazione è scritta in un linguaggio compilato e ampiamente 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 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 (ad es. 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 individuare eventuali problemi relativi alle modifiche nei tipi.
In ogni caso, la best practice prevede di eseguire test delle unità che applicano il codice dell'applicazione, incluse le chiamate all'API Looker (non le chiamate simulate).