Versionen im Vergleich

Schlüssel

  • Diese Zeile wurde hinzugefügt.
  • Diese Zeile wurde entfernt.
  • Formatierung wurde geändert.

...

Info

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: 

...

  • Zustandslosigkeit: Die Zugriffe auf die API sind zwar zustandslos hinsichtlich der durch einen Ressource-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 Request wird daher die Kenntnis 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: 

...

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 /wiki/spaces/pppdoc300/pages/667811929 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 /wiki/spaces/pppdoc300/pages/667811929, 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 "/wiki/spaces/pppdoc300/pages/121045462" 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 /wiki/spaces/pppdoc300/pages/134054027 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 /wiki/spaces/pppdoc300/pages/142704654).
  • Der Zugriff auf die Freigabe kann in der Prozessplattform per Whitelisting auf bestimmte IP-Adressbereiche begrenzt werden.

REST-Endpunkte

Auszug einfügen
Endpunkte
Endpunkte
nopaneltrue

Datenmodell

Allgemeine Fehlercodes

HTTP-Response-Codemögliche Fehlerursache
400ungültige Anfrage
401Login erforderlich / Session-Cookie ist nicht mitgesendet worden
403Dem verwendeten Nutzerkonto fehlen Berechtigungen zum Zugriff auf die Ressource
404Zur angefragten ID liegt kein Inhalt (mehr) vor

...