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 in anderen API-Versionen wirken sich erst dann 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 ist so konzipiert, dass sie den Looker-API-Endpunkten und somit auch Ihren Anwendungen Stabilität bietet.
Wenn wir Looker weitere Features und Funktionen hinzufügen, 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 Antworttypeigenschaften hinzu. In den meisten Fällen stellen Ergänzungen an der API keine funktionsgefährdenden Änderungen dar, sodass wir die vorhandene Version der API beibehalten können, ohne Auswirkungen auf vorhandenen Anwendungscode zu haben, der auf der API basiert. Möglicherweise sind in Ihrem bestehenden Anwendungscode neue Funktionen, Parameter oder Funktionen, die in nachfolgenden Looker-Releases enthalten sind, nicht bekannt.
Ä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 Looker-Instanz können mehrere API-Versionen nebeneinander existieren, sodass Sie entscheiden können, wann Sie ein Upgrade auf die neue API-Version durchführen möchten. 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 in der neuesten API-Versionsebene aufgerufen werden.
Eine Ausnahme stellen hierbei kritische Sicherheitsprobleme dar. Wenn wir ein kritisches Sicherheitsproblem im Zusammenhang mit einem bestimmten Teil der API feststellen, werden wir alles tun, was notwendig ist, um dieses Sicherheitsproblem so schnell wie möglich zu mindern. Dies kann dazu führen, dass die anfällige Funktion deaktiviert wird, bis eine geeignete Lösung verfügbar ist.
Wenn eine Funktion, Funktion oder Eigenschaft eingestellt werden muss, um eine bessere Implementierung oder Lösung zu schaffen, belassen wir die aktuelle API in der Regel unverändert, markieren aber die zugehörigen API-Endpunkte als "Veraltet", um anzugeben, dass Sie sich vom Endpunkt in Ihrem Anwendungscode entfernen sollten.
funktionsgefährdende und additive Änderungen an der API
Bei einer nicht abwärtskompatiblen Änderung wird ein vorhandenes Artefakt eines API-Endpunkt gelöscht oder umbenannt. 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
Eine additive Änderung kann dagegen an stabilen Endpunkten vorgenommen werden. Dazu gehören:
- Neue, optionale Parameter
- Neue Attribute in Antworten (wir betrachten dies nicht als als störend, da wir davon ausgehen, dass Ihr Code unbekannte Attribute in Antworten ignoriert, was in der REST API-Community üblich ist)
Wenn ein stabiler Looker-API-Endpunkt eine erhebliche Änderung erfordert, um mit einer neuen Architektur oder Funktionalität fortzufahren, wird die Änderung normalerweise einem neuen Endpunkt hinzugefügt und in eine neue API-Version gebündelt, damit der vorhandene API-Endpunkt unverändert bleibt.
Flags für API-Endpunkte
Die meisten API-Endpunkte gelten als stabil, das heißt, sie werden sich voraussichtlich nicht ändern. Looker gibt nur in extremen Fällen funktionsgefährdende Änderungen für stabile Endpunkte frei, z. B. um ein Sicherheitsproblem zu beheben.
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 bitte die Versionshinweise von Looker, um über Änderungen informiert zu werden.
- Verworfene Endpunkte sind Endpunkte, die weiterhin unterstützt werden und derzeit noch 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 eine zukünftige Version von Looker die Unterstützung für diesen Endpunkt entfernt, 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 nicht mehr unterstützte Funktion oder Eigenschaft verwendet, sollten Sie den Code so refaktorieren, dass das verworfene Element so schnell wie möglich ersetzt wird.
Beta- und verworfene 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 Ihr Client-SDK oder Ihre API-URL auf eine neue API-Version aktualisieren möchten, müssen Sie Ihren Anwendungscode überprüfen, um festzustellen, ob Sie etwas verwenden, das sich durch die neue API-Version geändert hat. Beachten Sie Folgendes:
- Suchen Sie in Ihrem Anwendungscode nach den aktualisierten Funktions-, Wert- und Attributnamen.
- Prüfen Sie, ob Ihr Anwendungscode Änderungen an Typen unterstützt (z. B. von Ganzzahl zu String).
- Prüfen Sie Ihren Code. Weitere Informationen dazu finden Sie im Abschnitt Code überprü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 Parametern oder Antworttypen in einer neuen API-Version, die im Widerspruch zum vorhandenen Code stehen, dank der Kompilierungstypüberprüfung und Compiler-Fehlermeldungen leicht erkennbar sein.
- Wenn Ihre Anwendung in einer locker typisierten dynamischen Sprache geschrieben ist (wie JavaScript, Ruby und Python), kann es schwieriger sein, 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 Laufzeiteinheitentests erforderlich, um Probleme im Zusammenhang mit Typenänderungen zu finden.
In allen Fällen empfiehlt es sich, Einheitentests durchzuführen, die Ihren Anwendungscode ausführen, einschließlich der Aufrufe der Looker-API (keine Mock-Aufrufe).