Die REST-API der PICTURE-Prozessplattform stellt eine programmatische Schnittstelle für die Interaktion mit ausgewählten Teilen des Datenmodells der PICTURE-Prozessplattform zur Verfügung, welche für typische Integrationsszenarien zur Einbindung von Drittsystemen relevant sind.
Der folgende Abschnitt des Informationsportals richtet sich an Techniker, die eine Integration von Drittanwendungen mit der PICTURE-Prozessplattform prüfen, konzipieren und realisieren möchten. Dazu stehen auf den folgenden Seiten Informationen zu folgenden Themen zur Verfügung:
- Überblick über die grundlegenden Paradigmen für den Umgang mit der Programmierschnittstelle (Programmiermodell)
- Hinweise zu Querschnittsaspekten der Nutzung wie z.B. Authentifizierung und Autorisierung
- Dokumentation der einzelnen Endpunkte der Schnittstelle zur Umsetzung der abgedeckten fachlichen Anwendungsfälle
- Dokumentation der für die Nutzung der Schnittstelle relevanten Teile des Datenmodells der PICTURE-Prozessplattform
Grundlagen
Die Programmierschnittstelle der Prozessplattform ist in Anlehnung an die Konventionen für eine RESTful-HTTP-API gestaltet. Sie weist insbesondere die folgenden Eigenschaften auf:
- alle verfügbaren Operationen werden auf HTTP-Verben (GET, POST, PUT, DELETE etc.) abgebildet
- alle Ressourcen lassen sich anhand ihrer URL eindeutig identifizieren.
Gegenüber der "reinen Lehre" bzgl. RESTful HTTP sind bei der Nutzung der API an folgenden Punkten Abweichungen zu erwarten:
- Zustandslosigkeit: Die Zugriffe auf die API sind zwar zustandslos hinsichtlich der durch einen Ressourcen-Aufruf modellierten Fachlichkeit, die Authentifizierung/Autorisierung des Aufrufers erfolgt jedoch session-basiert (Ausnahme: Portalzugriffe auf Basis von "Share Tokens").
- Repräsentationsformate für Nutzdaten (Inhalte von Request- und Response-Bodies): In der Regel liegen die Rückgabewerte im JSON-Format vor, in einigen Fällen in XML. Es findet keine Content Negotiation statt. Welches Format jeweils zurückgeliefert wird, kann der Dokumentation der einzelnen Endpunkte entnommen werden.
- Hypermedia as the engine of application state: Eine Verlinkung der verschiedenen Ressourcen-Repräsentationen inkl. Auflistung der für eine Ressource jeweils möglichen Operationen findet nicht statt. Zur Formulierung gültiger Requests wird daher die Kenntnis der in dieser Dokumentation beschriebenen REST-Endpunkte, ihrer Semantik und ihres URL-Adressierungsschemas vorausgesetzt.
Querschnittliche Aspekte der Nutzung
Authentifizierung & Autorisierung
Für Authentifizierung und Autorisierung unterstützt die Schnittstelle die folgenden beiden Vorgehensweisen:
- Session-basierte Authentifizierung auf Basis eines Benutzerkontos
- Authentifizierung per Access-Token im URL-Parameter auf Basis einer Portal-Freigabe.
Welche Vorgehensweise für einen bestimmten REST-Endpunkt zur Verfügung steht, ist in der jeweiligen Endpunkt-Dokumentation im Abschnitt "Möglichkeiten zur Authentifizierung & Autorisierung" angegeben.
Session-basierte Authentifizierung
- Für den Zugriff wird ein Benutzerkonto inkl. dessen Zugangsdaten (Benutzername und Passwort) benötigt.
- Die Authentifizierung mit diesem Benutzerkonto erfolgt durch einen programmatischen Login mit den Zugangsdaten des Benutzerkontos über einen REST-Endpunkt (die Verbindung ist hierbei grundsätzlich per HTTPS-Verschlüsselung geschützt). Nach erfolgreichem Login erzeugt der Login-Endpunkt ein Session-Cookie und sendet dieses an den Aufrufer zurück.
- Zugriffe auf sämtliche Ressourcen (abgesehen vom REST-Endpunkt für den Login selbst) setzen eine HTTP-Session voraus, die sich in die Prozessplattform eingeloggt hat. Hierzu muss bei jedem HTTP-Request auf eine geschützte Ressource das beim Login erhaltenen Session-Cookies im Header des Requests übermittelt werden.
- Für sämtliche Zugriffe auf geschützte Ressourcen wird zum Zwecke der Autorisierungsprüfung der Rechte-Kontext des eingeloggten, mit der HTTP-Session verknüpften Benutzerkontos ausgewertet.
- Die HTTP-Session wird von der Prozessplattform automatisch nach 20 Minuten Inaktivität getrennt.
- Erfolgt kein expliziter Logout, so kann bis zum Ablauf der Session keine neue Session mit den Zugangsdaten aufgebaut werden (Mehrfach-Login-Schutz).
Authentifizierung per "Share Token" (Portal-Freigabe)
- Ist für einen Prozessplattform-Mandanten zusätzlich das optionale Erweiterungspaket "Portalmodul" lizensiert, so steht zusätzlich zur session-basierten Authentifizierung für ausgewählte REST-Endpunkte die Möglichkeit zur Authentifizierung per Share Token zur Verfügung.
- Diese Art des Zugriffs kann für alle Inhalte genutzt werden, für die eine Portal-Freigabe erstellt wurde.
- Eine Freigabe in der Prozessplattform umfasst eine Menge von Prozessen / Prozesslandkarten. Die Authentifizierung des Zugriffs erfolgt über das Share Token der Freigabe, welches den Query-Parametern (&shareToken=...) des zugehörigen Freigabelinks entnommen werden kann (siehe dazu Freigaben verwalten).
- Der Zugriff auf die Freigabe kann in der Prozessplattform per Whitelisting auf bestimmte IP-Adressbereiche begrenzt werden.
REST-Endpunkte
Datenmodell
Allgemeine Fehlercodes
| HTTP-Response-Code | mögliche Fehlerursache |
|---|---|
| 400 | ungültige Anfrage |
| 401 | Login erforderlich / Session-Cookie ist nicht mitgesendet worden |
| 403 | Dem verwendeten Nutzerkonto fehlen Berechtigungen zum Zugriff auf die Ressource |
| 404 | Zur angefragten ID liegt kein Inhalt (mehr) vor |