Die meisten Anwendungen werden in einer Form eines Client-SDK oder möglicherweise einer API-URL geschrieben. Das Client-SDK und die API-URLs sind an eine bestimmte Looker API-Version gebunden. Ihre Anwendung funktioniert auch dann, wenn Looker Änderungen an neuen API-Versionen vornimmt. Änderungen in anderen API-Versionen wirken sich nicht auf Ihre Anwendung aus, bis Sie Ihr Client-SDK aktualisieren (oder die API-URL ändern), um die neue Looker API-Version zu verwenden.
Wie Looker Änderungen an der API vornimmt
Die Looker API ist so konzipiert, dass sie Stabilität für Looker API-Endpunkte und damit Stabilität für Ihre Anwendungen bietet.
Wenn wir weitere Funktionen zu Looker hinzufügen, aktualisieren wir auch die Looker REST API, um auf diese neuen Funktionen zuzugreifen oder diese zu verwalten. Für jede Looker-Version fügen wir der aktuellen Version der Looker-API neue API-Funktionen, Parameter und Antworttyp-Eigenschaften hinzu. In den meisten Fällen sind Ergänzungen der API keine funktionsgefährdenden Änderungen. Die vorhandene Version der API bleibt also bestehen, ohne dass sich dies auf vorhandenen Anwendungscode auswirkt, der auf der API basiert. Möglicherweise werden in Ihrem bestehenden Anwendungscode neue Funktionen, Parameter oder Merkmale nicht erkannt, die in nachfolgenden Looker-Versionen erscheinen.
Bei Änderungen an der API, die vorhandenen Anwendungscode beeinträchtigen würden, bündeln wir diese wichtigen Änderungen in einer neuen API-Version. Das bedeutet, dass die alte API-Version wie zuvor funktioniert, während gleichzeitig eine neue API-Version mit den Änderungen und Updates ausgeführt wird. In einer Looker-Instanz können mehrere API-Versionen gleichzeitig vorhanden sein, sodass Sie auswählen können, wann Sie ein Upgrade auf die neue API-Version durchführen möchten. Der bestehende Code, der zum Aufrufen des alten Endpunkts erstellt wurde, ruft weiterhin den alten Endpunkt auf. Neuer Code sollte die neue Version des Endpunkts auf der neuesten API-Versionsebene aufrufen.
Eine Ausnahme stellen kritische Sicherheitsprobleme dar. Wenn wir ein kritisches Sicherheitsproblem im Zusammenhang mit einem bestimmten Teil der API feststellen, werden wir alles tun, was erforderlich ist, um dieses Sicherheitsproblem so schnell wie möglich zu beheben. Dazu gehört die Deaktivierung der anfälligen Funktionen, bis eine geeignete Lösung verfügbar ist.
Wenn wir eine Funktion, eine Funktion oder eine Property aussortieren müssen, um Platz für eine bessere Implementierung oder Lösung zu schaffen, belassen wir die aktuelle API normalerweise so, kennzeichnen die zugehörigen API-Endpunkte jedoch als veraltet, um anzugeben, dass Sie den Endpunkt in Ihrem Anwendungscode entfernen sollten.
Wichtige und additive Änderungen an der API
Bei einer nicht abwärtskompatiblen Änderung wird ein vorhandenes Artefakt eines API-Endpunkt gelöscht oder umbenannt. Beispiele:
- Name oder Typ eines Parameters ändern oder löschen
- Neuen erforderlichen Parameter hinzufügen
- Basis-URL ändern
- Vorhandene Property in einer Antwort ändern oder löschen
Eine additive Änderung hingegen kann an stabilen Endpunkten vorgenommen werden. Beispiele:
- Neue, optionale Parameter
- Neue Eigenschaften in Antworten (wir betrachten dies nicht als funktionsunfähig, da wir davon ausgehen, dass Ihr Code unbekannte Eigenschaften 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, sodass der vorhandene API-Endpunkt unverändert bleibt.
Flags für API-Endpunkte
Die meisten API-Endpunkte gelten als stabil, sie werden sich also nicht ändern. 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 können als Beta oder eingestellt gekennzeichnet sein:
- 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 der Verwendung von Beta-Endpunkten, ob eine Änderung an der Looker-API Ihre Anwendung oder Ihren Entwicklungszyklus besonders beeinträchtigen würde. Lesen Sie die Versionshinweise von Looker, wenn Sie einen Beta-Endpunkt verwenden möchten, um über Änderungen informiert zu werden.
- Verworfene Endpunkte sind Endpunkte, die noch unterstützt werden und derzeit verwendet werden können, aber in einer zukünftigen Version gelöscht werden. Alter Code, der einen verworfenen Endpunkt verwendet, sollte aktualisiert werden, damit dieser nicht mehr verwendet wird. Wenn eine zukünftige Version von Looker die Unterstützung für diesen Endpunkt einstellt, funktionieren alle Codes, die ihn noch verwenden, nicht mehr. In den meisten Fällen wird ein verworfener Endpunkt durch eine verbesserte Funktionalität ersetzt. Wenn Sie feststellen, dass Ihre Anwendung eine veraltete Funktion oder Eigenschaft verwendet, sollten Sie Ihren Code so refaktorieren, dass das eingestellte 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 auf eine Änderung angewiesen sind, die sich in der neuen API-Version geändert hat. Gehen Sie dabei so vor:
- Suchen Sie in Ihrem Anwendungscode nach den aktualisierten Funktions-, Wert- und Eigenschaftsnamen.
- Prüfen Sie, ob Ihr Anwendungscode Änderungen an Typen (z. B. Ganzzahl in String) unterstützt.
- Prüfen Sie Ihren Code (siehe Abschnitt unten).
Code prüfen
Bei einigen Sprachen können funktionsgefährdende Änderungen in der API bei der Erstellung 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 zu Ihrem vorhandenen Code stehen, dank der Kompilierungstypprüfung und Compiler-Fehlermeldungen leicht erkennbar sein.
- Wenn Ihre Anwendung in einer lose typisierten 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. Für diese Sprachentypen sind möglicherweise Laufzeiteinheitentests erforderlich, um Probleme im Zusammenhang mit Typenänderungen zu ermitteln.
In allen Fällen empfiehlt es sich, Einheitentests durchzuführen, die Ihren Anwendungscode ausführen, einschließlich Aufrufen der Looker-API (keine simulierten Aufrufe).