PORTAL und PPS Knowledge Base

PRINT PPS API

Owned by Former user (Deleted), created
Last updated: 2024-10-17 by Ilker Oygün
3 min read

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

Allgemeine Beschreibung

Basis URL

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:

/oauth/v2

Methode:

GET /token

Parameter:

  • grant_type Muss immer den Wert “client_credentials” haben

  • client_id Die Client / Public ID

  • client_secret Das Secret (Passwort)

Rückgabewert:

  • Eine Access-Token-Datenstruktur (Bearer)

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.

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)

Nachdem die Zugänge erfolgreich erstellt wurden, finden sich dort pro Zugang die API-Credentials: Client ID und Client Secret.

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 AUTHORIZE in jedem Endpunkt aufgerufen werden.

Access Token

{ "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.

Methode:

[GET]  /token

Parameter:

  • grant_type Muss immer den Wert client_credentials haben

  • client_id Die Client-/Public-ID

  • client_secret Das Secret (Passwort)

Rückgabewert:

  • Eine Access-Token-Datenstruktur (siehe oben).

4. Verwenden der API

Basis URL

Alle API-Requests müssen über HTTPS ausgeführt werden. Requests über HTTP werden fehlschlagen. API-Requests ohne Autorisierung werden ebenfalls fehlschlagen.

Verwandte Seiten

 


Nur für PEIQ-Mitarbeiter:innen
https://peiq.atlassian.net/wiki/x/SQCqPw

Impressum