Die meisten Anwendungen werden mit einer Art Client-SDK oder möglicherweise einer API-URL geschrieben. Das Client-SDK und die API-URLs sind an eine bestimmte Looker API-Version gebunden. Ihre Anwendung funktioniert weiterhin, auch wenn Looker Änderungen an neuen API-Versionen vornimmt. Ihre Anwendung ist erst von Änderungen in anderen API-Versionen betroffen, wenn Sie Ihr Client-SDK aktualisieren oder die API-URL ändern, um die neue Looker API-Version zu verwenden.
So nimmt Looker Änderungen an der API vor
Die Looker API ist so konzipiert, dass sie Stabilität für Looker API-Endpunkte und damit auch für Ihre Anwendungen bietet.
Wenn wir Looker weitere Funktionen hinzufügen, aktualisieren wir auch die Looker REST API, damit Sie auf diese neuen Funktionen zugreifen oder sie verwalten können. Mit jeder Looker-Version fügen wir der aktuellen Version der Looker API neue API-Funktionen, Parameter und Antworttypparameter hinzu. In den meisten Fällen sind Ergänzungen der API keine nicht funktionsfähigen Änderungen. Wir können also die vorhandene Version der API beibehalten, ohne den vorhandenen Anwendungscode zu beeinträchtigen, der auf der API basiert. Möglicherweise sind in Ihrem vorhandenen Anwendungscode neue Funktionen, Parameter oder Features, die in nachfolgenden Looker-Versionen eingeführt werden, einfach nicht bekannt.
Änderungen an der API, die vorhandenen Anwendungscode beeinträchtigen würden, werden in einer neuen API-Version gebündelt. Das bedeutet, dass die alte API-Version weiterhin wie bisher funktioniert, während eine neue API-Version mit den Änderungen und Updates parallel dazu ausgeführt wird. Mehrere API-Versionen können in einer einzelnen Looker-Instanz nebeneinander vorhanden sein. So können Sie selbst entscheiden, wann Sie auf die neue API-Version umstellen. Ihr vorhandener Code, der für den Aufruf des alten Endpunkts entwickelt wurde, ruft weiterhin den alten Endpunkt auf. Im neuen Code sollte die neue Version des Endpunkts auf der neuesten API-Versionsebene aufgerufen werden.
Eine Ausnahme gilt für kritische Sicherheitsprobleme. Wenn wir ein schwerwiegendes Sicherheitsproblem im Zusammenhang mit einem bestimmten Teil der API entdecken, werden wir alles Notwendige tun, um dieses Sicherheitsproblem so schnell wie möglich zu beheben. Das kann auch bedeuten, dass wir die anfällige Funktion deaktivieren, bis eine geeignete Lösung verfügbar ist.
Wenn wir eine Funktion, Funktion oder Eigenschaft einstellen müssen, um Platz für eine bessere Implementierung oder Lösung zu schaffen, lassen wir die aktuelle API in der Regel unverändert, markieren die zugehörigen API-Endpunkte jedoch als eingestellt, um darauf hinzuweisen, dass Sie den Endpunkt in Ihrem Anwendungscode nicht mehr verwenden sollten.
Funktionsgefährdende und additive Änderungen an der API
Eine nicht abwärtskompatible Änderung ist eine Änderung, bei der ein vorhandenes Artefakt eines API-Endpunkt gelöscht oder umbenannt wird. Dazu kann Folgendes gehören:
- Parameternamen oder -typ ändern oder löschen
- Neuen erforderlichen Parameter hinzufügen
- Basis-URL ändern
- Vorhandene Property in einer Antwort ändern oder löschen
Eine additive Änderung kann hingegen an stabilen Endpunkten vorgenommen werden. Dazu gehören unter anderem:
- Neue optionale Parameter
- Neue Eigenschaften in Antworten (wir betrachten dies nicht als Breaking Change, da wir davon ausgehen, dass Ihr Code unbekannte Eigenschaften in Antworten ignoriert. Das ist in der REST API-Community üblich.)
Wenn für einen stabilen Looker API-Endpunkt eine erhebliche Änderung erforderlich ist, um mit einer neuen Architektur oder Funktionalität fortzufahren, wird die Änderung in der Regel einem neuen Endpunkt hinzugefügt und in einer neuen API-Version gebündelt, sodass der vorhandene API-Endpunkt unverändert bleibt.
Flags für API-Endpunkte
Die meisten API-Endpunkte gelten als stabil, d. h., sie werden sich voraussichtlich nicht ändern. Looker nimmt an stabilen Endpunkten keine Breaking Changes vor, es sei denn, es handelt sich um extreme Fälle, z. B. um ein Sicherheitsproblem zu beheben.
Andere API-Endpunkte können als Beta oder verworfen gekennzeichnet sein:
- Beta-Endpunkte befinden sich in der aktiven Entwicklung und können sich in Zukunft ändern. Sie sind nicht vor funktionsgefährdenden Änderungen geschützt. Wenn Sie Beta-Endpunkte verwenden, sollten Sie überlegen, ob eine Änderung an der Looker API besonders störend für Ihre App oder Ihren Entwicklungszyklus wäre. Wenn Sie einen Beta-Endpunkt verwenden möchten, lesen Sie bitte die Versionshinweise zu Looker, damit Sie über alle Änderungen informiert sind.
- Eingestellte Endpunkte werden weiterhin unterstützt und können derzeit noch verwendet werden, werden aber in einer zukünftigen Version gelöscht. Alter Code, der einen verworfenen Endpunkt verwendet, sollte aktualisiert werden, damit der verworfene Endpunkt nicht mehr verwendet wird. Wenn die Unterstützung für diesen Endpunkt in einer zukünftigen Version von Looker entfernt wird, funktioniert jeder Code, der ihn noch verwendet, nicht mehr. In den meisten Fällen wird ein eingestellter Endpunkt durch eine verbesserte Funktion ersetzt. Wenn Sie feststellen, dass Ihre Anwendung eine eingestellte Funktion oder Eigenschaft verwendet, sollten Sie Ihren Code so schnell wie möglich refaktorieren, um das eingestellte Element zu ersetzen.
Beta- und eingestellte Endpunkte sind im API Explorer und in der API-Referenz für Version 4.0 entsprechend gekennzeichnet. Endpunkte, die nicht markiert sind, gelten als stabil.
Arten von API-Aufrufen
Die folgenden Arten von API-Aufrufen werden als Abfrage-API-Aufrufe definiert:
- Aufrufe, die für automatisierte Abfragepipelines erforderlich sind
- Anrufe, bei denen Daten aus der Clientdatenbank abgerufen werden
- Aufrufe, mit denen SQL-Abfragen ausgeführt oder Ergebnisse für Inhalte abgerufen werden
Beispiele:
Die folgenden Arten von API-Aufrufen werden als Admin-API-Aufrufe definiert:
- Aufrufe, die zum Erstellen von Anwendungen, zum Steuern von Inhalten über Instanzen hinweg und zum Ausführen administrativer Aufgaben erforderlich sind
- Aufrufe zur Steuerung der Looker (Google Cloud Core)-Instanz
- Aufrufe, mit denen Inhalte, Berechtigungen und Nutzer verwaltet, Instanzen administriert oder Inhalte aus Ordnern abgerufen werden
Hier einige Beispiele:
Zu einer neuen API-Version migrieren
Wenn Sie ein Upgrade Ihres Client-SDK oder Ihrer API-URL auf eine neue API-Version durchführen, müssen Sie den Anwendungscode prüfen, um festzustellen, ob Sie etwas verwenden, das sich mit der neuen API-Version geändert hat. Achten Sie auf Folgendes:
- Suchen Sie im Anwendungscode nach den aktualisierten Funktions-, Wert- und Eigenschaftsnamen.
- Prüfen Sie, ob Ihr Anwendungscode Änderungen an Typen unterstützt (z. B. von Integer zu String).
- Prüfen Sie Ihren Code (siehe Code prüfen).
Code prüfen
Bei einigen Sprachen können Breaking Changes in der API zur Build-Zeit als Kompilierungsfehler erkannt werden:
- Wenn Ihre Anwendung in einer kompilierten, stark typisierten Sprache geschrieben ist, sollten strukturelle Änderungen an Parameter- oder Antworttypen in einer neuen API-Version, die mit Ihrem vorhandenen Code nicht kompatibel sind, dank der Kompilierungstypüberprüfung und Compilerfehlermeldungen leicht zu erkennen sein.
- Wenn Ihre Anwendung in einer dynamischen Sprache mit schwacher Typisierung (z. B. JavaScript, Ruby und Python) geschrieben wurde, ist es möglicherweise schwieriger, die Teile Ihrer Anwendung zu finden, die von wichtigen Änderungen in einer neuen API-Version betroffen sind. Bei diesen Sprachen sind möglicherweise Laufzeit-Einheitentests erforderlich, um Probleme im Zusammenhang mit Änderungen an Typen zu finden.
In jedem Fall ist es am besten, Einheitentests zu haben, die Ihren Anwendungscode ausführen, einschließlich Aufrufen der Looker API (nicht simulierter Aufrufe).