Die meisten Anwendungen werden in irgendeiner Form über ein Client SDK oder möglicherweise über eine API-URL geschrieben. Das Client-SDK und die API-URLs sind an eine bestimmte Looker API-Version gebunden. Ihre Anwendung funktioniert auch dann weiter, wenn Looker Änderungen an neuen API-Versionen vornimmt. Änderungen in anderen API-Versionen wirken sich erst dann auf Ihre Anwendung aus, wenn Sie ein Upgrade Ihres Client SDK durchführen oder die API-URL so ändern, dass die neue Looker API-Version verwendet wird.
So nimmt Looker Änderungen an der API vor
Die Looker API ist auf Stabilität für Looker API-Endpunkte und damit auf Stabilität für Ihre Anwendungen ausgelegt.
Wenn wir Looker um weitere Features erweitern, aktualisieren wir auch die Looker REST API, um auf diese neuen Features zuzugreifen oder sie zu verwalten. Für jede Looker-Version fügen wir der aktuellen Version der Looker API neue API-Funktionen, Parameter und Antworttypattribute hinzu. In den meisten Fällen sind Änderungen durch die Ergänzungen der API nicht funktionsgefährdend. Wir können also die vorhandene Version der API beibehalten, ohne dass sich der vorhandene Anwendungscode auf die API auswirkt. In Ihrem bestehenden Anwendungscode sind möglicherweise keine neuen Funktionen, Parameter oder Funktionen erkannt, die in nachfolgenden Looker-Versionen erscheinen.
Bei Änderungen an der API, die den vorhandenen Anwendungscode stören würden, fassen wir diese funktionsgefährdenden Änderungen in einer neuen API-Version zusammen. Das bedeutet, dass die alte API-Version wie gewohnt funktioniert, während eine neue API-Version mit den Änderungen und Aktualisierungen durchläuft. In einer Looker-Instanz können mehrere API-Versionen gleichzeitig vorhanden sein, sodass Sie auswählen können, wann ein Upgrade auf die neue API-Version durchgeführt werden soll. Der vorhandene Code, der zum Aufrufen des alten Endpunkts erstellt wurde, ruft weiterhin den alten Endpunkt auf. Mit neuem Code sollte die neue Version des Endpunkts auf der neuesten API-Versionsebene aufgerufen werden.
Eine Ausnahme bilden kritische Sicherheitsprobleme. Wenn wir ein kritisches Sicherheitsproblem im Zusammenhang mit einem bestimmten Teil der API feststellen, unternehmen wir alle notwendigen Schritte, um dieses Sicherheitsproblem so schnell wie möglich zu minimieren. Dazu gehört auch, dass die gefährdete Funktion deaktiviert wird, bis eine geeignete Lösung verfügbar ist.
Wenn wir eine Funktion, eine Funktion oder eine Property ausmustern müssen, um Platz für eine bessere Implementierung oder Lösung zu schaffen, lassen wir die aktuelle API in der Regel unverändert, aber kennzeichnen die zugehörigen API-Endpunkte als "eingestellt, um anzugeben, dass Sie den Endpunkt in Ihrem Anwendungscode verlassen sollten.
Funktionsgefährdende und additive Änderungen an der API
Mit einer nicht abwärtskompatiblen Änderung wird ein vorhandenes Artefakt eines API-Endpunkts gelöscht oder umbenannt. Beispiele:
- Parametername 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 dagegen an stabilen Endpunkten vorgenommen werden. Beispiele:
- Neue optionale Parameter
- Neue Eigenschaften in Antworten (wir berücksichtigen das nicht, weil wir davon ausgehen, dass Ihr Code unbekannte Eigenschaften in Antworten ignoriert. Dies ist in der REST API-Community üblich.)
Wenn ein stabiler Looker API-Endpunkt eine signifikante Änderung erfordert, um mit der neuen Architektur oder Funktionalität fortzufahren, wird die Änderung normalerweise 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 werden als stabil betrachtet, d. h., sie ändern sich nicht. Looker veröffentlicht keine funktionsgefährdenden Änderungen an stabilen Endpunkten, außer in extremen Fällen, z. B. um ein Sicherheitsproblem zu beheben.
Andere API-Endpunkte werden möglicherweise als Beta oder verworfen gekennzeichnet:
- Betaendpunkte befinden sich in der aktiven Entwicklung und können sich in Zukunft ändern. Sie sind nicht vor funktionsgefährdenden Änderungen geschützt. Überlegen Sie bei Verwendung von Betaendpunkten, ob eine Änderung an der Looker API Ihre App oder Ihren Entwicklungszyklus besonders stören 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 sind Endpunkte, die noch unterstützt werden und aktuell verfügbar sind. Sie werden aber in einer zukünftigen Version gelöscht. Alter Code, der einen verworfenen Endpunkt verwendet, sollte aktualisiert werden, damit er nicht mehr verwendet wird. Wenn in einer zukünftigen Version von Looker die Unterstützung für diesen Endpunkt eingestellt wird, funktioniert der gesamte Code, der ihn noch nutzt, nicht mehr. In den meisten Fällen wird ein eingestellter Endpunkt durch verbesserte Funktionen ersetzt. Wenn Sie feststellen, dass Ihre Anwendung eine veraltete Funktion oder Eigenschaft verwendet, empfiehlt es sich, den Code so bald wie möglich zu refaktorieren, um das veraltete Element zu ersetzen.
Betaversionen und eingestellte Endpunkte sind im API Explorer und in der API-Referenz 4.0 entsprechend gekennzeichnet. Endpunkte, die nicht markiert sind, gelten als stabil.
Zu einer neuen API-Version migrieren
Wenn Sie das Client-SDK oder die API-URL auf eine neue API-Version aktualisieren, müssen Sie Ihren Anwendungscode prüfen, um festzustellen, ob Sie sich auf eine Änderung verlassen haben, die sich mit der neuen API-Version geändert hat. Gehen Sie dabei so vor:
- Suchen Sie im Anwendungscode nach den aktualisierten Funktions-, Wert- und Attributnamen.
- Überprüfen Sie, ob Ihr Anwendungscode alle Arten von Änderungen unterstützt (z. B. Ganzzahl in String).
- Prüfen Sie Ihren Code (siehe Abschnitt unten).
Code prüfen
Bei einigen Sprachen werden funktionsgefährdende Änderungen beim Erstellen der API als Kompilierungsfehler erkannt:
- Wenn Ihre Anwendung in einer kompilierten, typisierten Sprache geschrieben ist, sollten strukturelle Änderungen an Parameter- oder Antworttypen in einer neuen API-Version, die mit Ihrem vorhandenen Code nicht vereinbar sind, dank der Kompilierung der Typprüfung und der Compiler-Fehlermeldungen leicht erkennbar sein.
- Wenn Ihre Anwendung in einer lose geschriebenen dynamischen Sprache geschrieben ist (z. B. JavaScript, Ruby und Python), ist es möglicherweise schwieriger, die Teile der Anwendung zu finden, die von Änderungen in einer neuen API-Version betroffen sind. Für diese Sprachen sind unter Umständen Laufzeiteinheitstests erforderlich, um Probleme mit Änderungen der Typen zu finden.
In jedem Fall empfiehlt es sich, Unittests durchzuführen, die Ihren Anwendungscode ausführen, einschließlich Aufrufen der Looker API (nicht simulierte Aufrufe).