Versionsverwaltung der Looker API

Die meisten Anwendungen werden in irgendeiner Form über ein Client SDK oder unter Umständen ü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 noch, wenn Looker Änderungen an neuen API-Versionen vornimmt. Ihre Anwendung ist erst von Änderungen in anderen API-Versionen betroffen, wenn Sie das Client-SDK upgraden 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 konstruiert, dass sie für Looker API-Endpunkte und somit Stabilität für Ihre Anwendungen sorgt.

Wenn wir Looker um weitere Features erweitern, wird auch die Looker REST API aktualisiert, um auf diese neuen Features zuzugreifen oder sie zu verwalten. Bei jedem Looker-Release werden der aktuellen Version der Looker API neue API-Funktionen, -Parameter und -Antworttypen hinzugefügt. In den meisten Fällen sind Hinzufügungen zur API keine funktionsgefährdenden Änderungen. Wir können die vorhandene API-Version also beibehalten, ohne Auswirkungen auf vorhandenen Anwendungscode zu haben, der auf der API basiert. In Ihrem vorhandenen Anwendungscode sind möglicherweise neue Funktionen, Parameter oder Features, die in nachfolgenden Looker-Releases enthalten sind, einfach nicht bekannt.

Bei Änderungen an der API, durch die vorhandener Anwendungscode beeinträchtigt werden würde, werden diese funktionsgefährdenden Änderungen in einer neuen API-Version zusammengefasst. Das bedeutet, dass die alte API-Version weiterhin wie gewohnt funktioniert, während eine neue API-Version mit den Änderungen und Aktualisierungen ausgeführt wird. In einer Looker-Instanz können mehrere API-Versionen nebeneinander vorhanden sein. So können Sie auswählen, wann auf die neue API-Version aktualisiert werden soll. Der vorhandene Code, der zum Aufrufen des alten Endpunkts erstellt wurde, ruft weiterhin den alten Endpunkt auf. Mit dem neuen 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, werden wir alles tun, um dieses Sicherheitsproblem so schnell wie möglich zu minimieren. Dazu gehört beispielsweise die Deaktivierung der gefährdeten Funktionalität, bis eine geeignete Lösung verfügbar ist.

Wenn wir eine Funktion, Funktion oder Eigenschaft ausmustern müssen, um eine bessere Implementierung oder Lösung zu ermöglichen, verwenden wir normalerweise die aktuelle API unverändert. Die zugehörigen API-Endpunkte werden jedoch als verworfen gekennzeichnet, um anzugeben, dass Sie in Ihrem Anwendungscode den Endpunkt entfernen sollten.

Funktionsgefährdende und zusätzliche Änderungen an der API

Eine funktionierende Änderung ist ein Vorgang, bei dem ein vorhandenes Artefakt eines API-Endpunkt gelöscht oder umbenannt wird. Dazu gehören:

  • Parameternamen oder -typen ändern oder löschen
  • Neuen erforderlichen Parameter hinzufügen
  • Basis-URL ändern
  • Property in einer Antwort ändern oder löschen

Eine zusätzliche Änderung kann hingegen an stabilen Endpunkten vorgenommen werden. Dazu gehören unter anderem:

  • Neue, optionale Parameter
  • Neue Attribute in Antworten (es gilt nicht für Fehler, weil wir annehmen, 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 der neuen Architektur oder Funktion voranzukommen, wird die Änderung in der Regel einem neuen Endpunkt hinzugefügt und zu einer neuen API-Version zusammengefasst, damit der vorhandene API-Endpunkt unverändert bleibt.

Flags für API-Endpunkte

Die meisten API-Endpunkte werden als stabil eingestuft und können daher nicht geändert werden. Looker gibt keine funktionsgefährdenden Änderungen an stabilen Endpunkten frei, außer in extremen Fällen, z. B. um ein Sicherheitsproblem zu beheben.

Andere API-Endpunkte können als Beta oder eingestellt gekennzeichnet werden:

  • Betaendpunkte befinden sich noch in der Entwicklungsphase und können sich in Zukunft ändern. Sie sind nicht vor funktionsgefährdenden Änderungen geschützt. Berücksichtigen Sie bei der Verwendung von Betaendpunkten, ob eine Änderung an der Looker API Ihre App oder Ihren Entwicklungszyklus beeinträchtigen könnte. Lesen Sie die Versionshinweise von Looker, wenn Sie einen Betaendpunkt verwenden möchten, um über Änderungen informiert zu sein.
  • Verworfene Endpunkte sind Endpunkte, die noch unterstützt werden und derzeit noch verwendet werden können. Sie werden 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 entfernt wird, funktioniert der gesamte Code, der noch verwendet wird. 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, ist es eine gute Idee, Ihren Code so bald wie möglich zu refaktorieren, um das eingestellte Element zu ersetzen.

Betaversionen und eingestellte Endpunkte sind im API Explorer und in der 4.0 API-Referenz entsprechend gekennzeichnet. Nicht markierte Endpunkte werden als stabil betrachtet.

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 prüfen, um festzustellen, ob Sie sich auf etwas verlassen, das sich mit der neuen API-Version geändert hat. Gehen Sie dabei so vor:

  1. Suchen Sie im Anwendungscode nach den aktualisierten Funktions-, Wert- und Attributnamen.
  2. Überprüfen Sie, ob Ihr Anwendungscode alle Typen unterstützt (z. B. Ganzzahlen in Strings).
  3. Prüfen Sie den Code (siehe Abschnitt unten).

Code prüfen

Bei einigen Sprachen können funktionsgefährdende Änderungen bei der Build-Erstellung als Fehler beim Kompilieren erkannt werden:

  • Wenn Ihre Anwendung in einer kompilierten, typisierten Sprache geschrieben wird, sollten strukturelle Änderungen an Parameter- oder Antworttypen in einer neuen API-Version, die mit Ihrem vorhandenen Code nicht übereinstimmen, dank der Kompilierungstyp-Überprüfung und Compiler-Fehlermeldungen leicht erkennbar sein.
  • Wenn Ihre Anwendung in einer locker geschriebenen dynamischen Sprache wie JavaScript, Ruby und Python geschrieben ist, ist es möglicherweise schwieriger, die Bereiche der Anwendung zu finden, die von funktionsgefährdenden Änderungen in einer neuen API-Version betroffen sind. Bei diesen Arten von Sprachen sind möglicherweise Laufzeiteinheitstests erforderlich, um Probleme im Zusammenhang mit Änderungen von Typen zu finden.

In jedem Fall empfehlen wir Einheitstests, mit denen Ihr Anwendungscode getestet wird. Dazu gehören auch Aufrufe der Looker API (keine simulierten Aufrufe).