API 2.0 Dokumentation PORTAL

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

1 Interaktive API Dokumentation nach Open API Spezifikation
2 Modulübersicht
3 Interaktive Bedienung – “Try it out”-Funktion
- 3.1 Parameter
- 3.2 Request Body
- 3.3 Response
- 3.4 Schema
4 Download der API Dokumentation
- 4.1 Download Dokumentation nach Open API Spezifikation
5 Trouble Shooting bei HTTP Status Codes
- 5.1 400 - Bad Request
- 5.2 401 - Unauthorized
- 5.3 404 - Not Found
- 5.4 409 - Conflict
6 Verwandte Seiten

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.

^{'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}

Download Dokumentation nach Open API Spezifikation

Downloadmöglichkeit der API Spezifikationsdatei, um diese beispielsweise in API Clients zu importieren.

Stand: Aug 26, 2022

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 GET -Requests ist das harte Limit von maximal 10.000 Results. Wir empfehlen daher, die Abfragen noch weiter einzugrenzen, z. B. monats- oder ortsweise, um so die Grenze zu umgehen.

`401` - Unauthorized

Fehlende OAuth-Authentifizierung. Um Zugriff auf die API zu erhalten, wird ein Access-Token benötigt. Dieses kann man sich über einen speziellen Endpunkt generieren, indem man sich mit Client ID und Client Secret authentifiziert.

Ggf. ist auch das aktuell genutzte Access-Token abgelaufen. In diesem Fall muss ein neues Access-Token beantragt werden.

`404` - Not Found

Der gesuchte Inhalt konnte nicht gefunden werden bzw. die gesetzten Filter finden keine Ergebnisse.

`409` - Conflict

Taucht beispielsweise bei der Routing API auf, falls versucht wird, ein Duplikat anzulegen.