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 ist ein gültiger API-Key.
Die Autorisierung erfolgt über den Button “Authorize” der jeweiligen Dokumentation. Hier müssen die API-Credentials (Client-ID und Client Secret) eingetragen 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.
'Try it out' Button
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
Verwandte Seiten
Disclaimer
Für die vorliegende Systemübersicht/Publikation behalten wir uns alle Rechte vor. Nachdruck, Vervielfältigung und Verbreitung (auch auszugsweise) ist nur mit schriftlicher Genehmigung der PEIQ Publishing GmbH & Co. KG erlaubt. Wir behalten uns vor, die Systemübersicht/Publikation jederzeit ohne vorherige Ankündigung zu ändern und/oder zu erweitern. Die vorliegenden Angaben dienen lediglich Informationszwecken. Die PEIQ Publishing GmbH & Co. KG übernimmt keinerlei Haftung und/oder Garantie für Fehler und/oder unvollständige Angaben in der Systemübersicht/Publikation, mit Ausnahme von vorsätzlich falschen oder arglistig verschwiegenen Angaben. Da unsere Software laufend weiter entwickelt wird, handelt es sich bei den vorliegenden nur um allgemeine Angaben. Es handelt sich weder um eine Zusicherung von Mindestvertragsinhalten, noch um Beschaffenheitsgarantien im Sinne des § 443 BGB.