PORTAL und PPS Knowledge Base
API 1.0 Dokumentation (PRINT PPS)
- Former user (Deleted)
- Ilker Oygün
- Kathrin Janka
Die interaktive Entwickler-Dokumentation der PRINT PPS API kann im System über die allgemeine Verwaltung erreicht werden. Voraussetzung hierfür ist die Berechtigung “Zugang zur API-Dokumentation”.
Funktionalitäten der API 1.0 Dokumentation
Aufbau nach Open-API-Spezifikation
Downloadmöglichkeit der Spezifikation im JSON-Format
Einfache Nutzung dank “Try it out”-Funktion
Inhaltsverzeichnis
Allgemeine Beschreibung
Open API Spezifikation
Die API-Dokumentation ist als interaktive Dokumentation für berechtigte Benutzer:innen direkt im PRINT PPS unter /api-dokumentation erreichbar. Die Spezifikation kann als JSON-Datei heruntergeladen werden und in REST-Clients wie z. B. Postman importiert werden, um direkt mit der Bedienung zu starten.
Das swagger-File kann auch hier heruntergeladen werden (Stand: Oct 10, 2022):
Verfügbare API Endpunkte
Replicas
GET /replicas:
Find Replicas
Gibt eine paginierte Liste an Ausgaben nach den gesetzten Filtern aus.
Issues
GET /replicas/{replica_id}/issues:
Find Issues
Gibt eine paginierte Liste an Ausgaben nach den gesetzten Filtern aus.
Collections
GET /replicas/{replica_id}/collections:
Find Collections
Gibt eine paginierte Liste an Sammlungen nach den gesetzten Filtern aus.
Articles
GET /issues/{issue_id}/articles:
Find Articles
Gibt alle Artikel mit der gesetzten Ausgaben-ID aus.
GET /colletions/{colletion_id}/articles:
Find Articles
Gibt alle Artikel mit der gesetzten Sammlungs-ID aus.
GET /articles/{article_id}:
get by ID
Gibt den Artikel mit der gesetzten Artikel-ID aus.
GET /related_articles/{article_id}:
get copies and inherited articles
Gibt alle Kopien und Vererbungen des Artikels mit der gesetzten Artikel-ID aus.
GET /articles/{article_id}/exportlog:
get Import/Export Log Entries
Gibt das Import/Export-Protokoll des Artikels mit der gesetzten Artikel-ID aus.
POST /articles/{article_id}/exportlog:
add Import/Export Log Entry
Befüllt das Import/Export-Protokoll des Artikels mit der gesetzten Artikel-ID.
GET /articles/categories:
Get all Article Aategories
Gibt eine Liste aller im PRINT PPS hinterlegten Kategorien zurück.
GET /articles/status:
Get all Article Status
Gibt alle Status zurück.
GET /articles/content_type:
Get all Article Content Types
Gibt alle Inhaltsarten zurück.
Images
GET /images/{image_id}:
return Image with ID
Gibt das Bild mit der gesetzten Image-ID zurück.
Autorisierung
Autorisierung über OAuth & Access-Token
Um Zugriff auf die API zu erhalten, wird ein Access-Token benötigt. Dieses kann sich über einen speziellen Endpunkt generieren, indem sich mit Client ID und Client Secret authentifiziert wird:
Prefix |
|
Methode: | GET /token |
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.
Um Zugriff auf die API zu erhalten, wird ein Access-Token benötigt. Dieses kann über einen speziellen Endpunkt generiert werden, indem mit Client ID und Client Secret authentifiziert wird.
Diese API-Credentials (Client ID und Client Secret) können über die Verwaltung von API Zugängen von berechtigten Benutzer:innen (Berechtigung “API Zugänge verwalten”) selbst erstellt werden.
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.
Interaktive Bedienung - Try it out
Die API 1.0 Dokumentation kann bereits ohne große Programmierkenntnisse oder ein darauf ausgerichtetes Programm bedient werden. Hierfür gibt es die “Try it out”-Funktion.
Jeder 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.
Auch zur Nutzung der Try-it-out-Funktion in der API 1.0 Dokumentation 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 Modul aufgerufen werden.
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. Sollten hierbei Fragen aufkommen, können Sie sich gerne an uns wenden.
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”.
Request Body
Um einen Request an die API zu senden, ist für jeden Endpunkt eine bestimmte Struktur für die PRINT PPS API festgelegt. Diese findet sich im Request-Body der API Dokumentation an allen schreibenden Endpunkten (POST).
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.
Schema
Über Schema lassen sich die Datentypen für jeden Parameter pro Endpunkt identifizieren.
Trouble Shooting bei HTTP-Status-Codes
400 - Bad Reqest
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.
404 - Not Found
Der gesuchte Inhalt konnte nicht gefunden werden bzw. die gesetzten Filter finden keine Ergebnisse.
Verwandte Seiten
Nur für PEIQ-Mitarbeiter:innen
https://peiq.atlassian.net/wiki/x/LQBzR