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. Swagger bietet dafür zwei Wege.

Durch einen Klick auf Authorize erscheint der Login-Dialog.

• Scheme oauth2: Login mit einem CMI-Benutzer am STS.
  • client_id ist vorgefüllt (Konfiguration CmiStsClientId) und bleibt unverändert. client_secret bleibt leer.
  • Ein Klick auf den Authorize-Button leitet zum STS weiter. Nach dem Login am STS sind die nachfolgenden Aufrufe autorisiert.
  • Client-ID und Secret eines Fremdsystems (z.B. ThirdPartyServiceClientId) funktionieren hier nicht. Dafür ist das Scheme Bearer vorgesehen.
• Scheme Bearer: Ein beim STS bezogenes Token einfügen. Das Token wird mit Client-ID und Secret über client_credentials bezogen, siehe Token-Request. Vor dem Token muss zwingend Bearer (mit Leerzeichen) stehen.

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.

GET Info/serverVersion

Dieser Endpoint gibt die Version des CMI Servers 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.