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 fornire stabilità per gli endpoint dell'API Looker e, di conseguenza, stabilità per le tue applicazioni.
Man mano che aggiungiamo altre caratteristiche 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à del tipo di risposta alla versione corrente dell'API Looker. Nella maggior parte dei casi, le aggiunte all'API non sono modifiche non compatibili, 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.
Per le modifiche all'API che danneggerebbero il codice dell'applicazione esistente, raggruppiamo quelle che interrompono le modifiche 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. In una singola istanza di Looker possono coesistere più versioni dell'API, 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 API più recente.
Fanno eccezione i problemi di sicurezza critici. Se rileviamo un problema di sicurezza critico relativo a una particolare parte dell'API, faremo tutto il necessario per mitigare il problema di sicurezza il prima possibile, inclusa 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 far posto a un'implementazione o a una soluzione migliore, di solito lasciamo invariata l'API attuale, ma contrassegniamo gli endpoint API associati come "deprecati" per indicare che è necessario allontanarsi dall'endpoint nel codice dell'applicazione.
Interruzione e modifiche aggiuntive all'API
Una modifica interrompente è qualcosa che elimina o rinomina un artefatto 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. che possono includere:
- 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 dell'API Looker stabile necessita di una modifica significativa per procedere con una nuova architettura o funzionalità, la modifica di solito viene aggiunta a un nuovo endpoint e bundle 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 è previsto alcun cambiamento. Looker non rilascerà modifiche che interrompono gli endpoint stabili se non in casi estremi, come per risolvere un problema di sicurezza.
Altri endpoint API possono essere contrassegnati come beta o ritirati:
- Gli endpoint beta sono in fase di sviluppo attivo e potrebbero cambiare in futuro. Non sono protette dalle modifiche che provocano un errore. Quando utilizzi endpoint beta, valuta se una modifica all'API Looker risulterebbe particolarmente fastidiosa 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 deprecati sono endpoint che sono ancora supportati e possono ancora 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 versione futura di Looker rimuoverà il supporto per quell'endpoint, qualsiasi codice che lo sta ancora utilizzando verrà interrotto. Nella maggior parte dei casi, un endpoint obsoleto verrà sostituito da funzionalità migliorate. 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 dell'API a una nuova versione dell'API, devi esaminare il codice dell'applicazione per vedere se ti stai basando su qualcosa che è cambiato 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 numero intero a stringa).
- Controlla il codice (consulta la sezione Controllo del codice).
Controllo del codice
Per alcuni linguaggi, le modifiche che provocano un errore nell'API possono essere rilevate in fase di creazione come errori di compilazione:
- Se la tua applicazione è scritta in un linguaggio compilato con tipi fortemente vincolati, 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 lingue potrebbero richiedere test delle unità di runtime per individuare 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).