Die meisten Anwendungen werden mit einer Art Client-SDK oder einer 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 an anderen API-Versionen wirken sich erst auf Ihre Anwendung aus, 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 wurde so konzipiert, dass die Looker API-Endpunkte und damit Ihre Anwendungen stabil sind.
Wenn wir Looker um weitere Funktionen erweitern, 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 Eigenschaften für den Antworttyp hinzu. In den meisten Fällen sind Ergänzungen der API keine wesentlichen Änderungen. Daher können wir die vorhandene Version der API beibehalten, ohne den vorhandenen Anwendungscode zu beeinflussen, der auf der API basiert. Möglicherweise sind in Ihrem vorhandenen Anwendungscode einfach keine neuen Funktionen, Parameter oder Features enthalten, die in nachfolgenden Looker-Releases eingeführt wurden.
Änderungen an der API, die den vorhandenen Anwendungscode beeinträchtigen würden, bündeln wir in einer neuen API-Version. Das bedeutet, dass die alte API-Version weiterhin wie gewohnt funktioniert, während eine neue API-Version mit den Änderungen und Updates parallel dazu ausgeführt wird. In einer einzelnen Looker-Instanz können mehrere API-Versionen nebeneinander existieren. So können Sie selbst entscheiden, wann Sie auf die neue API-Version umstellen möchten. Der vorhandene Code, der zum Aufrufen des alten Endpunkts erstellt wurde, ruft weiterhin den alten Endpunkt auf. Der neue Code sollte die neue Version des Endpunkts in der neuesten API-Version aufrufen.
Eine Ausnahme bilden kritische Sicherheitsprobleme. Wenn wir ein schwerwiegendes Sicherheitsproblem im Zusammenhang mit einem bestimmten Teil der API feststellen, ergreifen wir alle erforderlichen Maßnahmen, um dieses Sicherheitsproblem so schnell wie möglich zu beheben. Dazu kann auch die Deaktivierung der anfälligen Funktion gehören, bis eine geeignete Lösung verfügbar ist.
Wenn wir eine Funktion, ein Merkmal oder eine Property einstellen müssen, um Platz für eine bessere Implementierung oder Lösung zu schaffen, lassen wir die aktuelle API normalerweise unverändert, kennzeichnen die zugehörigen API-Endpunkte aber als „veraltet“, um anzuzeigen, 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, durch die ein vorhandenes Artefakt eines API-Endpunkt gelöscht oder umbenannt wird. Dazu 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
Bei stabilen Endpunkten kann hingegen eine additive Änderung vorgenommen werden. Dazu gehören:
- Neue optionale Parameter
- Neue Properties in Antworten (wir betrachten dies nicht als fehlerhaft, da wir davon ausgehen, dass unbekannte Properties in Antworten von Ihrem Code ignoriert werden, was in der REST API-Community üblich ist)
Wenn für einen stabilen Looker API-Endpunkt eine erhebliche Änderung erforderlich ist, um eine neue Architektur oder Funktion zu implementieren, wird die Änderung in der Regel einem neuen Endpunkt hinzugefügt und in einer neuen API-Version gebündelt, damit der vorhandene API-Endpunkt unverändert bleibt.
Flags für API-Endpunkte
Die meisten API-Endpunkte gelten als stabil, d. h., sie sollten sich nicht ändern. Looker veröffentlicht nur in extremen Fällen wesentliche Änderungen an stabilen Endpunkten, z. B. zur Behebung eines Sicherheitsproblems.
Andere API-Endpunkte können als Beta oder verworfen gekennzeichnet sein:
- Betaendpunkte befinden sich in der aktiven Entwicklungsphase und können sich in Zukunft ändern. Sie sind nicht vor funktionsgefährdenden Änderungen geschützt. Wenn Sie Betaendpunkte verwenden, sollten Sie überlegen, ob eine Änderung an der Looker API für Ihre App oder Ihren Entwicklungszyklus besonders störend wäre. Wenn Sie einen Betaendpunkt verwenden möchten, lesen Sie die Versionshinweisen von Looker, damit Sie über alle Änderungen informiert sind.
- Eingestellte Endpunkte sind Endpunkte, die derzeit noch unterstützt und verwendet werden können, aber in einer zukünftigen Version gelöscht werden. Alter Code, der einen eingestellten Endpunkt verwendet, sollte aktualisiert werden, damit der eingestellte Endpunkt nicht mehr verwendet wird. Wenn in einer zukünftigen Version von Looker die Unterstützung für diesen Endpunkt entfernt wird, funktioniert der Code, in dem er noch verwendet wird, nicht mehr. In den meisten Fällen wird ein eingestellter Endpunkt durch eine verbesserte Funktion ersetzt. Wenn Sie feststellen, dass in Ihrer Anwendung eine veraltete Funktion oder Eigenschaft verwendet wird, sollten Sie Ihren Code so bald wie möglich refaktorisieren, um das veraltete Element zu ersetzen.
Beta- und eingestellte Endpunkte sind im API Explorer und in der 4.0 API-Referenz entsprechend gekennzeichnet. Nicht gekennzeichnete Endpunkte gelten als stabil.
Zu einer neuen API-Version migrieren
Wenn Sie Ihr Client-SDK oder Ihre API-URL auf eine neue API-Version umstellen, müssen Sie Ihren Anwendungscode prüfen, um festzustellen, ob Sie Funktionen verwenden, die sich mit der neuen API-Version geändert haben. Beachten Sie Folgendes:
- Suchen Sie in Ihrem Anwendungscode nach den aktualisierten Funktions-, Wert- und Property-Namen.
- Prüfen Sie, ob Ihr Anwendungscode Änderungen an Typen unterstützt (z. B. von Ganzzahl zu String).
- Prüfen Sie Ihren Code (siehe Abschnitt Code prüfen).
Code prüfen
Bei einigen Sprachen können bahnbrechende Änderungen an der API zur Kompilierungszeit 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 nicht mit Ihrem vorhandenen Code übereinstimmen, dank der Typprüfung bei der Kompilierung und Compilerfehlermeldungen leicht erkennbar sein.
- Wenn Ihre Anwendung in einer dynamisch und locker typisierten Sprache wie JavaScript, Ruby oder Python geschrieben wurde, ist es möglicherweise schwieriger, die Teile Ihrer Anwendung zu finden, die von bahnbrechenden Änderungen in einer neuen API-Version betroffen sind. Bei diesen Sprachen sind möglicherweise Laufzeit-Unit-Tests erforderlich, um Probleme im Zusammenhang mit Änderungen an Typen zu finden.
In jedem Fall empfiehlt es sich, Unit-Tests zu haben, die Ihren Anwendungscode testen, einschließlich Aufrufen der Looker API (keine gemockten Aufrufe).