Die meisten Anwendungen werden mit einer Form eines 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 auch dann noch, wenn Looker Änderungen an neuen API-Versionen vornimmt. Ihre Anwendung ist erst dann 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.
Änderungen an der Looker API
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, um auf diese neuen Funktionen zuzugreifen oder sie zu verwalten. Für jede Looker-Version fügen wir der aktuellen Version der Looker API neue API-Funktionen, Parameter und Eigenschaften des Antworttyps hinzu. In den meisten Fällen sind diese Ergänzungen keine funktionsgefährdenden Änderungen, sodass wir die vorhandene Version der API beibehalten können, ohne den vorhandenen Anwendungscode zu beeinträchtigen, der auf der API basiert. Ihr vorhandener Anwendungscode ist möglicherweise einfach nicht mit neuen Funktionen, Parametern oder Features kompatibel, die in nachfolgenden Looker-Versionen eingeführt werden.
Änderungen an der API, die vorhandenen Anwendungscode beeinträchtigen würden, werden in einer neuen API-Version zusammengefasst. 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, sodass Sie selbst entscheiden können, wann Sie auf die neue API-Version umsteigen. Ihr vorhandener Code, der für den Aufruf des alten Endpunkts entwickelt wurde, ruft weiterhin den alten Endpunkt auf. Neuer Code sollte die neue Version des Endpunkts in der neuesten API-Version aufrufen.
Eine Ausnahme gilt für kritische Sicherheitsprobleme. Wenn wir ein kritisches Sicherheitsproblem im Zusammenhang mit einem bestimmten Teil der API entdecken, werden wir alles tun, um dieses Sicherheitsproblem so schnell wie möglich zu beheben. Dazu gehört möglicherweise auch, die anfällige Funktion zu deaktivieren, bis eine geeignete Lösung verfügbar ist.
Wenn wir eine Funktion oder Eigenschaft einstellen müssen, um Platz für eine bessere Implementierung oder Lösung zu schaffen, lassen wir die aktuelle API normalerweise unverändert, markieren die zugehörigen API-Endpunkte aber als "verworfen". So wissen Sie, dass Sie den Endpunkt in Ihrem Anwendungscode nicht mehr verwenden sollten.
Funktionsgefährdende und additive Änderungen an der API
Eine funktionsgefährdende Änderung ist eine Änderung, bei der ein vorhandenes Artefakt eines API-Endpunkt gelöscht oder umbenannt wird. Dazu gehören beispielsweise:
- Ändern oder Löschen eines Parameternamens oder -typs
- Hinzufügen eines neuen erforderlichen Parameters
- Ändern der Basis-URL
- Ändern oder Löschen einer vorhandenen Eigenschaft in einer Antwort
Eine additive Änderung kann dagegen an stabilen Endpunkten vorgenommen werden. Dazu gehören beispielsweise:
- Neue optionale Parameter
- Neue Eigenschaften in Antworten (wir betrachten dies nicht als funktionsgefährdend, da wir davon ausgehen, dass Ihr Code unbekannte Eigenschaften in Antworten ignoriert. Das ist in der REST API-Community üblich.)
Wenn ein stabiler Looker API-Endpunkt eine erhebliche Änderung benötigt, um mit einer neuen Architektur oder Funktion weiterentwickelt zu werden, wird die Änderung in der Regel einem neuen Endpunkt hinzugefügt und in einer neuen API-Version zusammengefasst, sodass der vorhandene API-Endpunkt unverändert bleibt.
Flags für API-Endpunkte
Die meisten API-Endpunkte gelten als stabil, d. h., sie werden voraussichtlich nicht geändert. Looker nimmt keine funktionsgefährdenden Änderungen an stabilen Endpunkten 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 werden aktiv entwickelt 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 Ihre App oder Ihren Entwicklungszyklus besonders beeinträchtigen würde. Lesen Sie die Versionshinweise von Looker, wenn Sie einen Beta-Endpunkt verwenden möchten, damit Sie über alle Änderungen informiert sind.
- Verworfene Endpunkte werden noch 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 verworfener Endpunkt durch eine verbesserte Funktion ersetzt. Wenn Sie feststellen, dass Ihre Anwendung eine verworfene Funktion oder Eigenschaft verwendet, sollten Sie Ihren Code so schnell wie möglich refaktorieren, um das verworfene Element zu ersetzen.
Beta- und verworfene Endpunkte sind im API Explorer und in der API-Referenz 4.0 entsprechend gekennzeichnet. Endpunkte, die nicht gekennzeichnet sind, gelten als stabil.
Arten von API-Aufrufen
Die Arten von API-Aufrufen, die als Abfrage-API-Aufrufe definiert sind, sind folgende:
- Aufrufe, die für automatisierte Abfragepipelines erforderlich sind
- Aufrufe, die Daten aus der Clientdatenbank abrufen
- Aufrufe, die SQL-Abfragen ausführen oder Ergebnisse für Inhalte abrufen
Beispiele:
Die Arten von API-Aufrufen, die als Admin-API-Aufrufe definiert sind, sind folgende:
- Aufrufe, die zum Erstellen von Anwendungen, zum Steuern von Inhalten in verschiedenen Instanzen und zum Ausführen von Verwaltungsaufgaben erforderlich sind
- Aufrufe, die die Looker (Google Cloud Core)-Instanz steuern
- Aufrufe, die die Inhaltsverwaltung, die Berechtigungs- und Nutzerverwaltung, die Instanzverwaltung oder das Abrufen von Inhalten aus verschiedenen Ordnern ausführen
Beispiele:
Zu einer neuen API-Version migrieren
Wenn Sie Ihr Client-SDK oder Ihre API-URL auf eine neue API-Version aktualisieren, müssen Sie Ihren Anwendungscode überprüfen, um festzustellen, ob Sie etwas verwenden, das sich mit der neuen API-Version geändert hat. Achten Sie darauf, Folgendes zu tun:
- Suchen Sie in Ihrem Anwendungscode nach den aktualisierten Funktions-, Wert- und Eigenschaftsnamen.
- Prüfen Sie, ob Ihr Anwendungscode Änderungen an Typen unterstützt (z. B. von Ganzzahl zu String).
- Prüfen Sie Ihren Code (siehe den Abschnitt Code prüfen).
Code prüfen
In einigen Sprachen können funktionsgefährdende Änderungen 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 der Compilerfehlermeldungen leicht zu erkennen sein.
- Wenn Ihre Anwendung in einer dynamischen Sprache mit schwacher Typisierung (z. B. JavaScript, Ruby und Python) geschrieben ist, ist es möglicherweise schwieriger, die Teile Ihrer Anwendung zu finden, die von funktionsgefährdenden Änderungen in einer neuen API-Version betroffen sind. Für diese Arten von Sprachen sind möglicherweise Unit-Tests zur Laufzeit erforderlich, um Probleme im Zusammenhang mit Änderungen an Typen zu finden.
In jedem Fall ist es empfehlenswert, Unit-Tests zu haben, die Ihren Anwendungscode ausführen, einschließlich Aufrufen der Looker API (nicht simulierter Aufrufe).