| Info |
|---|
Mithilfe der PEIQ PRINT PPS APIs können Verlage über digitale Kanäle bestehende Inhalte aus dem PRINT PPS verwenden. Alle PRINT PPS APIs sind nach der REST-Architektur aufgebaut. Der Zugriff erfolgt dadurch mit den Standard HTTP-Methoden GET und POST. Die Zugriffskontrolle erfolgt hierbei über eine Implementierung nach OAuth V2 Standard. |
Funktionalitäten der PRINT PPS API
Anbindung bestehender Systeme
Interaktive Entwickler-Dokumentation mit potenziellen Anwendungsmöglichkeiten der verfügbaren APIs
Verwendung des OAuth V2 Standards für die Zugriffskontrolle
Inhaltsverzeichnis
| Expand | ||||
|---|---|---|---|---|
| ||||
|
Allgemeine Beschreibung
Basis URL
| Code Block |
|---|
https://domain.tld/api/v2/ |
Alle API-Requests müssen über HTTPS ausgeführt werden. Requests über HTTP werden fehlschlagen. API-Requests ohne Autorisierung werden ebenfalls fehlschlagen.
Autorisierung
Autorisierung über OAuth & Access Token
Um Zugriff auf die API zu erhalten, wird ein Access Token benötigt. Dieses kann über einen speziellen Endpunkt generiert werden, indem sich mit Client ID und Client Secret authentifiziert wird:
...
Prefix: |
| |||
Methode: |
|
...
Funktionalitäten der PRINT PPS API
tba
Inhaltsverzeichnis
| Expand | ||||
|---|---|---|---|---|
| ||||
|
Verwandte Seiten
...
| ||||
Parameter: |
| |||
Rückgabewert: |
|
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 (PRINT PPS)
Anleitung zur Verwendung der API
Folgende Berechtigungen werden für die Verwendung der API im PRINT PPS benötigt:
“Anlegen und bearbeiten von API Zugängen”
“Zugriff auf API-Dokumentation”
Es hat sich bewährt, für diese Art der Berechtigungen eine eigene Rolle (z. B. API Manager) anzulegen und diese ausgewählten Benutzer:innen zuzuweisen.
| Note |
|---|
Achtung: Mit den API-Zugangsdaten sollte sehr sorgsam umgegangen werden, da durch diese Daten aus dem PRINT PPS abgerufen oder geändert werden können. Aus diesem Grund sollte auch die Berechtigung zur API-Verwaltung nur ausgewählten internen Kolleg:innen gegeben werden. |
1. Einrichtung der API Zugänge / Autorisierungsdaten
Die benötigten API Zugänge können über die Verwaltung für API Zugänge erstellt werden. Eine detaillierte Anleitung ist hier zu finden: API Zugänge verwalten (PRINT PPS)
| Note |
|---|
Die dort gegebenen Hinweise zur Verwaltung der Zugänge müssen beachtet werden. |
Nachdem die Zugänge erfolgreich erstellt wurden, finden sich dort pro Zugang die API-Credentials: Client ID und Client Secret.
Die API-Credentials können als “read-only” und bei einem Endpunkt auch als “read-and-write” eingerichtet werden. Bei einem “read-and-write”-Modus können die Livedaten geändert/gelöscht werden. Aus diesem Grund sollten diese Credentials für “read-and-write”-Zugänge nur an vertrauenswürdigen Dritte weitergegeben werden.
Wird Dritten der API Zugang durch den bzw. die Kund:in zur Verfügung gestellt, wird empfohlen, dass der bzw. die Kund:in eigenständig mit diesen Dritten einen AVV (Vertrag zur Auftragsverarbeitung) abschließt.
2. Zugang zur API 1.0 Dokumentation
Die interaktive Entwickler-Dokumentation der PEIQ PRINT PPS API kann in jedem PRINT PPS über die allgemeine Verwaltung > API Dokumentation (oder über die relative URL /api-dokumentation) erreicht werden.
Dort befindet sich eine interaktive Dokumentation. Die Dokumentation kann dort dann als Open-API-Spezifikation zur Verwendung mit verschiedenen REST-Clients (z. B. Postman) heruntergeladen werden.
Weitere Details (z. B. auch zur Try-it-out-Funktion) finden sich unter API 1.0 Dokumentation (PRINT PPS).
3. Autorisierung
Bei der Zugangskontrolle handelt es sich um eine Implementierung nach dem OAuth V2 Standard. Auf die Details des Protokolls wird im Folgenden nicht eingegangen, stattdessen wird anhand von Beispielen demonstriert, wie die API zum Anfordern von Access Token verwendet werden kann.
Bundle Prefix | /oauth/v2 |
Beispiel URL | /oauth/v2/token |
Autorisierung bei “Try it out”
Auch zur Nutzung der “Try it out”-Funktion in der API 1.0 Dokumentation (PRINT PPS) ist eine Authentifizierung mittels Client Credentials erforderlich. Es muss hierfür kein Access Token angefordert werden.
Das Formular zur Autorisierung kann über den grünen Button
| Status | ||||
|---|---|---|---|---|
|
Nach einer gewissen Zeit läuft die Autorisierung ab, sodass die Try-it-out-Funktion nicht mehr funktioniert. In diesem Fall müssen Benutzer:innen das Formular erneut öffnen und sich aus- und wieder einloggen. Dann funktioniert die Try-it-out-Funktion wieder wie erwartet.
Access Token
| Code Block |
|---|
{
"token_type": <string>, // id.g. "Bearer"
"expires_in": <int>, // Zeitraum in Sekunden, die das Token gültig ist
"access_token": <string>, // Access Token
} |
Workflow
Das Anfordern von Access Token über die client_credentials erfordert die obigen Client ID und Client Secret. Die Methode ähnelt dem Login der Benutzer:innen mit Benutzername und Passwort, es wird aber keine Session initialisiert und das Access Token ist auch nicht an eine:n Benutzer:in gebunden.
| Note |
|---|
Achtung: Da diese Access Token mit System-Rechten ausgestattet und dementsprechend sehr mächtig sind, sollten sie niemals das Backend verlassen oder über unsicheren Wege verschickt werden. |
Methode: |
| ||
Parameter: |
| ||
Rückgabewert: |
|
4. Verwenden der API
Basis URL
| Code Block |
|---|
https://domain.tld/api/v2 |
Alle API-Requests müssen über HTTPS ausgeführt werden. Requests über HTTP werden fehlschlagen. API-Requests ohne Autorisierung werden ebenfalls fehlschlagen.
Verwandte Seiten
| Filter by label (Content by label) | ||||||||||
|---|---|---|---|---|---|---|---|---|---|---|
|
| Include Page | ||||
|---|---|---|---|---|
|
Nur für PEIQ-Mitarbeiter:innen
https://peiq.atlassian.net/wiki/x/SQCqPw