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

• PicJSON

• PicXML 3.0

Allgemeine Fehlercodes