Die interaktive Entwicklerdokumentation der PEIQ Cloud-Connect API kann über die Administration & Moderation oder unter /admin/api aufgerufen werden. Voraussetzung hierfür ist die Berechtigung “Zugang zur API-Dokumentation” |
Funktionalitäten der API 2.0 Dokumentation
Aufbau nach Open-API-Spezifikation
Downloadmöglichkeit pro Modul oder der kompletten API 2.0 Dokumentation im JSON-Format
Einfache Nutzung dank “Try it out”-Funktion
Inhaltsverzeichnis
Interaktive API Dokumentation nach Open API Spezifikation
Die im PORTAL erreichbare interaktive API Dokumentation ist nach der OpenAPI-Spezifikation mithilfe der Open Source Plattform Swagger aufgebaut. Swagger ist ein Softwareanbieter aus Massachusetts, USA, der Open Source Tools rund um die Entwicklung von RESTful APIs anbietet. Die Dokumentation ist interaktiv gestaltet und bietet eine Übersicht der potenziellen Anwendungsmöglichkeiten der diversen APIs im PEIQ PORTAL. Voraussetzung für den Zugang zur interaktiven Dokumentation ist die Berechtigung “Zugang zur API-Dokumentation”.
Modulübersicht
Die Modulübersicht zeigt auf einen Blick, welche Module in dem jeweiligen PORTAL aktiv und damit auch welche APIs potenziell verfügbar sind. Um eine API benutzen zu können, muss die API für das jeweilige Modul von PEIQ eingerichtet werden. Dies geschieht im Rahmen einer Änderungsanfrage.
Die Modulübersicht zeigt alle potenziell verfügbaren APIs im PEIQ PORTAL.
Detaillierte Beschreibung der APIs:
Interaktive Bedienung – “Try it out”-Funktion
Die Dokumentation selbst ist nicht nur rein informativer Natur, sondern bietet darüber hinaus die Möglichkeit, sämtliche lesende (GET) Endpunkt direkt zu testen. Über diese “Try it out”-Funktion können also Live-Daten aus dem System direkt im JSON-Format exportiert werden. Über die “Try it out”-Funktion können auch noch nicht freigeschaltete APIs unverbindlich getestet werden.
Jeder API-GET-Endpunkt der Dokumentation hat einen “Try it out” Button. Hierüber können Daten nach den im Front-End vorliegenden Filtern aus dem Live-System abgerufen werden. Bedingung für das Benutzen der Funktion sind gültige API-Credentials.
Diese API-Credentials (Client ID und Client Secret) können
über die Verwaltung von API-Zugängen von berechtigten Benutzer:innen selbst erstellt werden: API Zugänge verwalten
bei PEIQ beantragt werden, sofern das Feature API-Konsole nicht aktiviert ist.
Die Autorisierung erfolgt über den grünen Button “Authorize” der jeweiligen Dokumentation. Hier müssen die API-Credentials (Client-ID und Client Secret) über eine Maske eingetragen und bestätigt werden.
“Authorize” zum Eintragen der API-Credentials
Nach gewisser Zeit ist eine erneute Autorisierung der API-Credentials erforderlich, da es zum Ablauf der Autorisierung kommen kann.
Nach gewisser Zeit ist eine erneute Autorisierung der API-Credentials erforderlich, da es zum Ablauf der Autorisierung kommen kann.
'Try it out' Button
Um ein versehentliches Manipulieren der Daten zu verhindern, ist die Benutzung auf die lesenden Endpunkte (GET) beschränkt.
Um ein versehentliches Manipulieren der Daten zu verhindern, ist die Benutzung auf die lesenden Endpunkte (GET) beschränkt.
Parameter
Je nach API Endpunkt liegen verschiedene Parameter vor, die zur Bedienung der API herangezogen werden können. Welcher Datentyp für den jeweiligen Filter genutzt werden kann, findet sich unter Schema.
Parameter der API Endpunkte
Request Body
Um einen Request an die API zu senden, ist für jeden Endpunkt eine bestimmte Struktur für die PEIQ API festgelegt. Diese findet sich im Request Body der API Dokumentation an allen schreibenden Endpunkten (CREATE, DELETE).
Request Body
Response
Der Bereich Response beschreibt die möglichen Response-Codes, die für den Endpunkt verfügbar sind. Außerdem liegt ein Beispiel-body (“Example Value”) vor, über den sich die Struktur des Response identifizieren lässt.
Response-Codes mit Beispiel-body
Schema
Über Schema lassen sich die Datentypen für jeden Parameter pro Endpunkt identifizieren.
Request Body Schema
Download der API Dokumentation
Die Dokumentation kann pro Modul oder komplett (über die Modulübersicht) heruntergeladen werden. Die heruntergeladene JSON Datei kann in REST-Clients wie z.B. Postman importiert werden, um direkt mit der Bedienung zu starten.
Downloadmöglichkeit der API Spezifikationsdatei, um diese beispielsweise in API Clients zu importieren
Download Dokumentation nach Open API Spezifikation
Downloadmöglichkeit der API Spezifikationsdatei, um diese beispielsweise in API Clients zu importieren.
Stand:
Trouble Shooting bei HTTP Status Codes
400 - Bad Request
Der Request war nicht akzeptabel. Das liegt oft an einem fehlenden Parameter. Hier ist der gesendete Request Body zu prüfen. Eine weitere Ursache bei |