REST API: Erweiterte Endpunkt-Einstellungen

Dieses Topic beschreibt den Dialog Erweiterte Einstellungen eines REST-API-Endpunkts: allgemeine Optionen, Richtlinien-Einstellungen und OpenAPI-Fehlercodes. Eine Übersicht über die REST API-Konfiguration finden Sie unter REST API.

Allgemeine erweiterte Einstellungen

Ein Klick auf den Button Erweiterte Einstellungen öffnet einen modalen Dialog mit weiteren Endpunkt-Einstellungen.

Die Checkbox Eingabe muss gefüllt sein (inputMandatory) entscheidet, ob ein Eingabewert verpflichtend ist. Standard: optional.

Die Checkbox Anonymer Zugriff (allowAnonymousAccess) entscheidet, ob der Endpunkt anonymen Zugriff erlaubt. Standard: nicht erlaubt. Details zum Verhalten und zu den Risiken finden Sie unter Zugriffskontrolle für APIs.

 ACHTUNG 

Geben Sie einen Endpunkt für anonymen Zugriff nur in seltenen Ausnahmefällen frei. Das gilt besonders in einem öffentlich erreichbaren Produktivsystem. Unbedachte oder missbräuchliche Aufrufe können je nach Workflow weitreichende Folgen für Datensicherheit und Verfügbarkeit haben.

Ist veraltet (Sunset)

Die Checkbox Ist veraltet (isDeprecated) markiert einen Endpunkt als veraltet. Damit nehmen Sie ihn nach einer Karenzzeit kontrolliert außer Betrieb.

• Sobald die Option aktiv ist, erscheint ein Datum/Uhrzeit-Element. Dort geben Sie den Sunset-Zeitpunkt minutengenau an. Bis zu diesem Zeitpunkt bleibt der veraltete Endpunkt verfügbar.

• Bis zum Sunset-Zeitpunkt bleibt der Endpunkt in Betrieb. Die OpenAPI-Dokumentation kennzeichnet ihn aber bereits als „veraltet".

• Ein Aufruf nach dem Sunset-Zeitpunkt antwortet mit HTTP-Fehler 410 Error: Gone.

• Zusätzlich erscheint ein Textfeld für mehrzeiligen Text. Dort tragen Sie eine Abschaltwarnung ein.

• Der Text der Abschaltwarnung erscheint in den Response-Headern unter dem Schlüssel warning mit dem Code 299, solange der Sunset-Zeitpunkt in der Zukunft liegt.

• In diesem Zeitraum zeigt der Endpunkt im GUI und in der OpenAPI-Dokumentation die visuelle Kennzeichnung für veraltete Endpunkte (zum Beispiel durchgestrichener Text).

Die Plattform bildet die Informationen zur bevorstehenden Abschaltung auf Variablen ab. Auf diese greifen Sie im Aktionsblock über den Variable-Wertauflöser zu:

Das Textfeld Beschreibung (description) befüllen Sie optional mit informativem Klartext. Sie dokumentieren damit die Endpunkt-Konfiguration.

Richtlinien-Einstellungen (policySettings)

Der Tab-Reiter Richtlinien-Einstellungen im unteren Bereich des Dialogs Erweiterte Einstellungen verwaltet die Richtlinien für den Zugriff auf den Endpunkt. Die Einträge stehen im Listenfeld policySettings der Endpunkt-Definition.

Wozu dienen Richtlinien-Einstellungen?

Richtlinien-Einstellungen definieren Obergrenzen für die Zugriffsfrequenz eines Endpunkts zur Laufzeit.

Ein Endpunkt kann mehrere Richtlinien-Einstellungen parallel nutzen. So modellieren Sie eine zulässige Charakteristik für die Zugriffshäufigkeit flexibel.

Jede einzelne Richtlinie bezieht sich auf ein bestimmtes Zeitfenster. Für dieses Zeitfenster legt sie eine maximale Anzahl von Zugriffen auf den Endpunkt fest.

Mit zwei Richtlinien formulieren Sie zum Beispiel folgende Charakteristik:

• Ein API-Endpunkt darf innerhalb von 24 Stunden höchstens 500-mal aufgerufen werden.

• Der zeitliche Abstand zwischen zwei Aufrufen beträgt mindestens 30 Sekunden.

Verletzt ein Aufrufversuch eine dieser beiden Richtlinien, antwortet die Plattform mit HTTP-Fehler 429 Error: Too Many Requests im Response Body. Details zur verletzten Richtlinie liefern die Response-Header.

Im Dialog erscheinen die konfigurierten Richtlinien-Einstellungen in einem Datengrid. Oberhalb der Liste zeigt ein Detailbereich die Eigenschaften des ausgewählten Eintrags über Formularelemente an.

• Standardmäßig gibt es keine Richtlinien-Einstellungen.

• Der Button Neu () fügt einen Listeneintrag hinzu.

• Der Button Entfernen () entfernt den angezeigten Eintrag.

Jede Richtlinie ist ein Listeneintrag vom Typ Richtlinien-Einstellungen (PolicySettings) mit folgenden Eigenschaften:

• Das Auswahlfeld/Combobox Richtlinie (policy) erlaubt eine Einfachauswahl aus der Aufzählung (Klasse Policy) zur Klassifikation der Richtlinie.

• Das Feld Max. Zugriffe (maxRequests) legt die Obergrenze für die zulässige Anzahl von Zugriffen im konfigurierten Zeitfenster fest.

• Das Feld Zeitfenster in Millisek. (timeFrameMs) definiert das Zeitfenster für die Obergrenze.

 HINWEIS Alle Felder sind Pflichtfelder. Jede neue Richtlinie müssen Sie vollständig parametrieren.

OpenAPI-Fehlercodes

Der Tab-Reiter OpenAPI-Fehler-Codes im unteren Bereich des Dialogs Erweiterte Einstellungen verwaltet Fehlercodes für die OpenAPI-Dokumentation. Die Einträge stehen im Listenfeld statusCodes der Endpunkt-Definition.

Die Liste reichert die OpenAPI-Dokumentation um alternative Rückgabewerte an. Diese Rückgabewerte ergänzen den regulären Response mit HTTP-Statuscode 200.

 WICHTIG  Änderungen im Tab-Reiter OpenAPI-Fehler-Codes müssen Sie speichern, damit sie in der OpenAPI-Dokumentation erscheinen.

Sie legen die Einträge manuell über die Benutzeroberfläche an. Alternativ klicken Sie auf den Button Profile nach geworfenen HTTP-Fehlern durchsuchen oben im Tab-Reiter. Die Plattform durchsucht dann alle im Aktionsblock adressierten Profile nach Aufrufen der Funktion throwHttpException(). Findet sie Statuscodes, die noch nicht in der Liste stehen, hängt sie diese an.

•  HINWEIS Existiert für einen Statuscode bereits ein Listeneintrag, ändert der Suchlauf den Eintrag nicht.

• Erwarten Sie nach einer Profil-Änderung neuen Content für einen bereits gelisteten Statuscode, entfernen Sie den veralteten Eintrag manuell. Klicken Sie anschließend erneut auf Profile nach geworfenen HTTP-Fehlern durchsuchen.

• Bei der Suche nicht mehr gefundene Statuscodes entfernt die Plattform nicht automatisch. Sie kennzeichnet sie auch nicht als verwaist.

 WICHTIG  Vergeben Sie Werte für HTTP-Statuscodes in der Spalte HTTP-Antwortcodes strikt eindeutig. Sonst kann die OpenAPI-Dokumentation verwirren.

• Per Definition liegen HTTP-Response-Statuscodes als positive Ganzzahlen zwischen 100 und 599.

• Für Client Errors verwendet die Spezifikation positive Ganzzahlen zwischen 400 und 499.

• Über die Benutzeroberfläche können Sie auch Ganzzahlen außerhalb dieses Bereichs zuweisen.

• Die Funktion throwHttpException() akzeptiert für den korrespondierenden Parameter Zeichenfolgen für positive Ganzzahlen von 0 bis 999.

• Führende Nullen können Sie für Werte unter 100 eingeben und speichern. Für die Übernahme in die statusCodes-Liste ignoriert die Plattform diese aber.

 WARNUNG  Enthält die statusCodes-Liste den HTTP-Statuscode 200, übersteuert die zugehörige Definition die OpenAPI-Darstellung für den Rückgabewert. Standardmäßig leitet sich diese aus dem Typhinweis für die Variable response im Aktionsblock ab.

 ANMERKUNG In den folgenden Beispielen liegen die Statuscodes bewusst außerhalb des offiziellen Wertebereichs.

Endpunkt-Konfiguration

Auszug aus der OpenAPI-Dokumentation für den Endpunkt