Swagger

In Swagger sind alle Endpunkte sowie Models beschrieben. Jeder Endpunkt lässt sich testen, indem dieser aufgeklappt und auf "Try it out" gedrückt wird. Anschliessend müssen die notwendigen Parameter ausgefüllt werden.

• https://<CMI API>:<Port>/<Mandant>/swagger/index.html

Swagger einer Gruppe ist erreichbar unter:

• https://<CMI API>:<Port>/<Mandant>/groups/<Gruppenname>/swagger/index.html

In Swagger sind mehrere Definitionen vorhanden, welche über das Dropdown ausgewählt werden können:

• CMI API Model: Swaggerdefinition für die generische API mit den ausgewählten Typdefinitionen
• CMI API Process: Swaggerdefinition für die Prozess-Layer. Jeder Layer hat dabei seine eigene Definition.
• CMI API Debug: Swaggerdefinition für Debugging-Endpunkte wie zum Beispiel "Info"

Authentifizierung

Damit die API verwendet werden kann, braucht es ein Token. Wenn man ein Bearer Token beim STS bezogen hat, so kann unter Authorize dieses Token eingefügt werden.

• Token-Request

Durch einen Click auf Authorize erscheint der Login Dialog.

Hier muss nun entweder ein bereits erzeugtes Token eingefügt werden oder ein im STS hinterlegter client_credentials-Flow konfiguriert werden. (1)

Nach einem Klick auf den dazugehörigen Authorize-Button sind die nachfolgenden Aufrufe authorisiert.

Swagger codiert möglicherweise client_id und client_secret nicht korrekt, was zu Fehlern in der Anmeldung führen kann.
In diesem Fall müssen die Daten dort bereits codiert eingefügt werden.
Dafür kann z.B. urlencoder.org verwendet werden.
In der Regel solte das allerdings nicht notwendig sein.

OpenAPI Definition

Über Swagger kan man sich auch ein OpenAPI Json-File generieren.
Dies erreicht man, indem man das swagger.json öffnet:

Über den Swagger-Editor können diverse Clients generiert werden.

Debug-Endpoint

Jeder Mandant und jede Gruppe stellt Debug-Endpoints zur Verfügung. Um die Swagger-Definition für den Debug-Endpoint einer bestimmten Gruppe zu öffnen, kann die "CMI API Debug" im entsprechenden Swagger nachgeschlagen werden.

Info

GET Info

Dieser Endpoint gibt die aktuelle STS-Konfiguration des Mandanten zurück.

GET Info/version

Dieser Endpoint gibt die Version der CMI API zurück.

State

GET State/monitoring

Hier werden Monitoring-Daten für jede aufgerufene Anfrage bereitgestellt. Pro Anfrage werden die folgenden Informationen angezeigt:

• Request: Die vollständige URL
• Method: Die HTTP-Methode
• Median: Der Median der Anfragezeiten
• Average: Der Durchschnitt der Anfragezeiten
• TotalRequest: Die Anzahl der Anfragen

Die angezeigten Anfragen beziehen sich auf die letzten Minuten, wie in der Konfiguration unter ClearMonitoringDataAfterXMinutes festgelegt.

GET State/throttling

Hier werden alle Anfragen aufgeführt, die aufgrund des Throttle-Mechanismus blockiert wurden.

Die angezeigten Anfragen beziehen sich auf die letzten Minuten, wie in der Konfiguration unter ClearMonitoringDataAfterXMinutes festgelegt.