Die meisten Anwendungen werden mit einem 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 weiterhin, wenn Looker Änderungen an neuen API-Versionen vornimmt. Ihre Anwendung ist von Änderungen in anderen API-Versionen erst dann 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 bietet Stabilität für Looker API-Endpunkte und somit auch eine höhere Stabilität für Ihre Anwendungen.
Wenn wir Looker um weitere Funktionen erweitern, aktualisieren wir auch die Looker REST API, um auf diese neuen Features zuzugreifen oder sie zu verwalten. Für jeden Looker-Release fügen wir der aktuellen Version der Looker API neue API-Funktionen, -Parameter und -Antworttypen hinzu. In den meisten Fällen stellen Ergänzungen der API keine funktionsgefährdenden Änderungen dar, sodass die vorhandene Version der API beibehalten werden kann, ohne vorhandenen Anwendungscode zu beeinträchtigen, der auf der API basiert. Ihr vorhandener Anwendungscode kennt möglicherweise einfach keine neuen Funktionen, Parameter oder Features, die in nachfolgenden Looker-Versionen erscheinen.
Bei Änderungen an der API, bei denen vorhandener Anwendungscode nicht mehr funktionieren 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 gleichzeitig vorhanden sein, sodass Sie auswählen können, wann ein Upgrade auf die neue API-Version ausgeführt werden soll. 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 auf der neuesten API-Versionsebene aufrufen.
Hiervon ausgenommen sind kritische Sicherheitsprobleme. Wenn wir ein kritisches Sicherheitsproblem im Zusammenhang mit einem bestimmten Teil der API feststellen, werden wir alle notwendigen Schritte unternehmen, um dieses Sicherheitsproblem so schnell wie möglich zu beheben. Dazu gehört auch die Deaktivierung der anfälligen Funktion, bis eine geeignete Lösung verfügbar ist.
Wenn wir eine Funktion, eine Funktion oder eine Property außer Kraft setzen müssen, um eine bessere Implementierung oder Lösung zu ermöglichen, behalten wir die aktuelle API bei, wie sie ist, aber kennzeichnen wir die zugehörigen API-Endpunkte als verworfen, um sie in Ihrem Anwendungscode vom Endpunkt wegzubewegen.
Nicht abwärtskompatible und additive Änderungen an der API
Eine funktionsgefährdende Änderung ist ein Vorgang, bei dem ein vorhandenes Artefakt eines API-Endpunkts gelöscht oder umbenannt wird. Folgende Angaben sind möglich:
- Parameternamen oder -typen ä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 Attribute in Antworten (wir berücksichtigen dies nicht, 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 wesentliche Änderung erfordert, um mit neuer Architektur oder Funktionalität fortzufahren, wird die Änderung normalerweise einem neuen Endpunkt hinzugefügt und zu einer neuen API-Version gebündelt, damit der vorhandene API-Endpunkt unverändert bleibt.
Flags für API-Endpunkte
Die meisten API-Endpunkte werden als stabil angesehen, d. h., sie werden sich nicht ändern. Looker gibt keine funktionsgefährdenden Änderungen an stabile Endpunkte weiter, 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. Wenn Sie Betaendpunkte verwenden, überlegen Sie, ob eine Änderung an der Looker API besonders störend für Ihre App oder Ihren Entwicklungszyklus wäre. Wenn Sie einen Beta-Endpunkt verwenden möchten, lesen Sie die Versionshinweise von Looker, damit Sie über Änderungen informiert werden.
- Verworfene Endpunkte sind Endpunkte, die noch unterstützt werden und derzeit verwendet werden können. Sie werden in einer zukünftigen Version gelöscht. Altcode, 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 eingestellte Funktion oder Eigenschaft verwendet, sollten Sie Ihren Code so bald wie möglich überarbeiten, um das eingestellte Element zu ersetzen.
Beta- und verworfene Endpunkte sind in der API-Referenz entsprechend gekennzeichnet. Endpunkte, die nicht gekennzeichnet 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üssen Sie Ihren Anwendungscode daraufhin überprüfen, ob Sie sich auf eine Version 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.
- Prüfen Sie, ob Ihr Anwendungscode alle Typen unterstützt (z. B. Ganzzahl in String).
- Prüfen Sie Ihren Code (siehe Abschnitt unten).
Code prüfen
Bei einigen Sprachen können funktionsgefährdende Änderungen bei der Build-Erstellung 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 Kompilierungstypprüfung und der Compiler-Fehlermeldungen sofort ersichtlich sein.
- Wenn Ihre Anwendung in einer locker geschriebenen dynamischen Sprache wie 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. Bei diesen Arten von Sprachen sind möglicherweise Laufzeiteinheitstests erforderlich, um Probleme mit Änderungen der Typen zu finden.
In allen Fällen empfiehlt es sich, Einheitentests auszuführen, die Ihren Anwendungscode ausführen, einschließlich Aufrufen der Looker API (keine simulierten Aufrufe).