Der i-net PDFC-Server stellt eine Vielzahl von Funktionen über eine Web-API Schnittstelle zur Verfügung. Dazu benötigen die Benutzer die Web API-Zugriffs-Berechtigung. Darüber hinaus kann es erforderlich sein, dass Benutzer auch Berechtigungen für bestimmte weitere Funktionen im System haben müssen.

Die Web-API kann auf zwei Arten genutzt werden: interaktiv über die Web-API-Oberfläche und programmatisch über einen Client wie curl oder eine generierte Client-Bibliothek. Die folgenden Abschnitte beschreiben zuerst die Oberfläche und anschließend den programmatischen Zugriff. Die vollständige API ist in Swagger-Dateien beschrieben, aus denen sich auch Clients erzeugen lassen (siehe Swagger-Dateien).

Die folgende Liste von API-Endpunkten steht dem aktuellen Benutzer zur Verfügung:

Die Liste der Erweiterungen steht im Help Center Modus nicht zur Verfügung.

Die Web-API-Oberfläche ermöglicht das Durchsuchen der verfügbaren Web-API-Erweiterungen, das Lesen der Dokumentation zu jedem Endpunkt und das Ausprobieren im Browser.

Anfragen können in gewissem Umfang angepasst werden: Benutzer können die HTTP-Methode (POST, GET, HEAD ...) festlegen, dynamische Teile der URL aktualisieren, z.B. IDs, die bestimmte WebAPI-Kontexte ansprechen, Anfrage-Header sowie das Anfrage-JSON setzen.

Der URL-Pfad ist in der Regel nicht editierbar, mit Ausnahme der Teile, die z.B. IDs akzeptieren. Wenn Sie ID-Teile bearbeiten und in der Seitennavigation weiter navigieren, werden diese ID-Teile für die aktuelle Seite gespeichert, so dass Sie nahtlos vor- und zurückspringen können. Das erneute Senden einer Anfrage erfolgt über die Schaltfläche Senden.

Über das Optionsmenü neben der Schaltfläche Senden können Sie den Vorschau-Modus aktivieren, den JSON-Dateneingabebereich und den Bereich für zusätzliche HTTP Anfrage-Header einblenden.

Zusätzliche benutzerdefinierte HTTP-Parameter können zusammen mit einer Anfrage gesendet werden, wenn dies von einem WebAPI-Endpunkt verlangt wird. Dies können z. B. format- oder file-Parameter sein.

Zusätzliche benutzerdefinierte HTTP-Header können mit einer Anfrage mitgeschickt werden, wenn ein WebAPI-Endpunkt dies erfordert. Dies können z.B. Bearer Token sein.

Der Bereich JSON-Anfragedaten senden ermöglicht das Mitsenden einer JSON-Anfrage, die für einen bestimmten WebAPI-Endpunkt erforderlich ist. Hinweise auf das benötigte JSON werden in der Regel auf der Hilfeseite unterhalb des Antwortbereichs gegeben.

Hinweis: Einige HTTP-Methoden unterstützen das Senden von JSON-Daten nicht. Der Bereich ist dann deaktiviert.

Der Vorschaumodus ist eine Option im Antwortfenster der Web API Oberfläche. Wenn er aktiviert ist, sendet er zusätzliche Informationen an den Server. Annotationsbasierte Standardoperationen zum Erstellen, Ändern und Löschen arbeiten dann nur mit lokalen Anfragedaten und speichern ihre Änderungen nicht. Benutzerdefinierte Aktionen müssen eine nebenwirkungsfreie Vorschau ausdrücklich unterstützen.

Bestehende Web API Handler entscheiden weiterhin selbst, wie sie Vorschauanfragen behandeln. Der Vorschaumodus ist besonders für potenziell destruktive Befehle wie Löschen sinnvoll.

Der Antwortbereich der Web API Oberfläche besteht aus der Anfrage-URL, dem Antwortstatus-Code und der Nachricht. Ein Optionsfeld ermöglicht das Umschalten des Vorschaumodus (standardmäßig eingeschaltet).

Wenn die Antwortstatus-Nachricht nicht gesetzt wurde, wird eine generische Nachricht angezeigt (drei Punkte: ...). Dies geschieht normalerweise, wenn ein API-Punkt binäre Daten zurückschickt.

Hinweis: Binäre Datenantworten können dazu führen, dass anstelle einer JSON-Antwort (oder anderer verfügbarer Formate) ein Download-Button angezeigt wird. Die Anfrage wird beim klick auf die Download Schaltfläche erneut ausgelöst. Das bedeutet, dass der Befehl auf dem Server zweimal ausgeführt wird.

Dieser Abschnitt beschreibt, wie die Web-API über einen Client wie curl oder eine generierte Client-Bibliothek angesprochen wird.

Dieser Abschnitt führt anhand des Task Planner durch eine erste Anfrage. Die Schritte gelten entsprechend für jede andere Web-API-Erweiterung.

Für den programmatischen Zugriff auf die Web-API benötigen Sie die Berechtigung Web API-Zugriff sowie die Berechtigung der gewünschten Erweiterung, zum Beispiel Task Planner. Details finden Sie unter Berechtigungen.

Alle Anfragen werden an den /api-Kontext des Servers gesendet, zum Beispiel https://[HOST]:[PORT]/api/<erweiterung>/[Befehl]. Eine erste lesende Anfrage, die die Aufgaben des aktuellen Benutzers auflistet, sieht so aus:

# Aufgaben mit Basis-Authentifizierung auflisten
curl -Lsu benutzername:passwort "https://[HOST]:[PORT]/api/taskplanner/list"

Die Option -L folgt Weiterleitungen, -s unterdrückt die Fortschrittsausgabe und -u aktiviert die Basis-Authentifizierung. Für den skriptgesteuerten Zugriff verwenden Sie stattdessen die Token-Authentifizierung (siehe Authentifizierung). Die verfügbaren Befehle einer Erweiterung, einschließlich ihrer Parameter, Anfrageinhalte und Antwortfelder, sind auf den eigenen Hilfeseiten der jeweiligen Erweiterung beschrieben. Die Befehle des Task Planner sind unter Task Planner aufgelistet.

Anfragen an die Web-API erfordern eine ordnungsgemäße Authentifizierung. Für den programmatischen Zugriff verwenden Sie das Token-Authentifizierungs-Plugin, das den Benutzer bei jeder Anfrage anmeldet, ohne eine Sitzung zu erstellen.

Jede Sitzung verbraucht Speicher und verlangsamt den Server.

Vermeiden Sie das BASIC-Authentifizierungsschema für den skriptgesteuerten Zugriff, da es bei jeder Anmeldung eine neue Sitzung erstellt.

Erstellen Sie in der Administration ein Token und wählen Sie die Berechtigungen aus, die das Token verwenden darf. Für jeden registrierten Web-API-Kontext stellt das Plugin eine passende Token-Berechtigung bereit: Für /api/taskplanner lautet der Berechtigungsschlüssel webapi.taskplanner. Die Berechtigung gilt für den gesamten Baum unterhalb von /api/taskplanner und wird einem Token nicht automatisch erteilt, sondern muss beim Erstellen oder Bearbeiten des Tokens ausgewählt werden. Das Token wird anschließend mit jeder Anfrage gesendet:

# Aufgaben mit einem Bearer-Token auflisten
curl -LsH "Authorization: Bearer <access_token>" "https://[HOST]:[PORT]/api/taskplanner/list"

Bei Verwendung des BASIC-Authentifizierungsschemas wird eine Sitzung erstellt. Verwenden Sie diese Sitzung für nachfolgende Anfragen wieder, indem Sie das Sitzungs-Cookie mit jeder Anfrage senden; andernfalls sammeln sich unnötige Sitzungen an und verlangsamen den Server. Um die Anzahl der innerhalb eines bestimmten Zeitraums erstellten Sitzungen zu begrenzen, steht ein zusätzliches Defender Plugin zur Verfügung, das den Benutzer und die IP bei Überschreitung für die Anmeldung sperrt.

Das Fehlerformat hängt davon ab, ob der Endpunkt annotationsbasiert oder ein Legacy-Endpunkt ist. Annotationsbasierte Endpunkte liefern eine strukturierte JSON-Fehlerantwort:

{
  "status": 400,
  "code": "validation_failed",
  "message": "Die Aufgabe konnte nicht gespeichert werden.",
  "details": [
    {
      "location": "body",
      "path": "name",
      "code": "required",
      "message": "Ein Aufgabenname ist erforderlich."
    }
  ]
}

Hinweis: Fehlerantworten verwenden immer Content-Type: application/json. Interne Ausnahmemeldungen werden nie mitgesendet; Clients sollten sich auf den stabilen code-Wert statt auf den message-Text verlassen.

Legacy-Endpunkte wie der Task Planner verwenden diese Struktur nicht. Sie signalisieren Fehler mit einem HTTP-Fehlerstatus und einem JSON-Objekt, das nur eine benutzerfreundliche Meldung enthält:

{ "error": "Die Aufgabe konnte nicht gespeichert werden." }

Es gibt keinen stabilen maschinenlesbaren Fehlercode und keine strukturierten Details.

Die Web-API verwendet standardmäßige HTTP-Statuscodes. Die folgenden Codes sind für Clients am wichtigsten:

Eine Leseoperation kann dieselben Daten in verschiedenen Darstellungen anbieten. Wählen Sie eine Darstellung über den Accept-Header oder, sofern verfügbar, über den Query-Parameter format:

# Nicht-JSON-Darstellung ueber den Accept-Header auswaehlen
curl -LsH "Accept: text/csv" "https://[HOST]:[PORT]/api/<erweiterung>/[Befehl]"
 
# Darstellung ueber den format-Parameter auswaehlen
curl -Ls "https://[HOST]:[PORT]/api/<erweiterung>/[Befehl]?format=csv"

Ein ausdrücklich gesetzter format-Parameter hat Vorrang vor dem Accept-Header. JSON ist die Standarddarstellung.

Annotationsbasierte Endpunkte unterstützen den globalen Query-Parameter fields, um JSON-Antworten zu verkleinern. Es werden nur die aufgelisteten Eigenschaften ausgegeben:

# Nur id und name zurueckgeben
curl -Ls "https://[HOST]:[PORT]/api/<erweiterung>/<id>?fields=id,name"

Hinweis: fields filtert nur die Antwort; die Dokumentation und die Swagger-Datei beschreiben weiterhin alle lesbaren Eigenschaften.

Die Web-API kann Swagger-Dateien generieren, die in externen Tools zur Erstellung benutzerdefinierter Clients verwendet werden können. Sie können entweder eine vollständige Swagger-JSON-Datei über die URL <you-server>/api/swagger.json herunterladen. Sie können auch eine spezielle URL für Web-API-Kontexte erhalten, indem Sie den Erweiterungspfad einfügen, z. B. <your-server>/api/taskplanner/swagger.json.

Hinweis: Die Swagger-URLs können optional in der Konfiguration privat gestellt werden. Sind die URLs privat, müssen sich Clients vor dem Herunterladen der Datei authentifizieren.

Laden Sie die Swagger-Datei des gewünschten Kontexts herunter, zum Beispiel <you-server>/api/taskplanner/swagger.json, und erzeugen Sie damit einen Client für Ihre Programmiersprache. Mit dem OpenAPI-Generator lautet die Anfrage:

# Java-Client aus der Swagger-Datei erzeugen
openapi-generator generate -i https://[HOST]:[PORT]/api/taskplanner/swagger.json -g java -o ./taskplanner-client

Die installierten OAuth2-Provider unterstützten zusätzlich das Token/Bearer-Authentifizierungsschema. Das Token muss mit dem Header Authorization: Bearer <access_token> gesendet werden. Das Token selbst muss beim Ursprungsprovider, z.B. GitHub, erzeugt werden. Das Token wird dann gegen den ursprünglichen OAuth-Anbieter geprüft - siehe OpenID Spezifikation.

# REQUEST
POST /api HTTP/1.1
Authorization: Bearer VGhpcyBpcyBqdXN0IGEgZGVtbyBhY2Nlc3MgdG9rZW4u
Content-Type: application/json

Einem Benutzer, der durch ein Zugriffstoken authentifiziert wird, werden die gleichen Berechtigungen gewährt, die der Benutzer mit seinen Anmeldedaten hätte.

Die Windows-Authentifizierung mit NTLM ist ein Authentifizierungsprotokoll auf der Grundlage von Challenge-Response, das mehrere Anfragen erfordert, um den Vorgang abzuschließen. Im Folgenden werden die einzelnen Schritte des Prozesses beschrieben:

1. Der Client leitet den Authentifizierungsprozess ein, indem er eine Anfrage an den API-Endpunkt sendet. Dies kann entweder geschehen durch:
   • Hinzufügen des Abfrageparameters ?login=windows zur URL
   • oder durch Senden der Anfrage mit einem Authorization: NTLM-Kopfzeile
2. Der Server antwortet mit einer Challenge in Form eines NTLM-Tokens, das der Client verwenden muss, um eine Antwort zu berechnen.
3. Der Client sendet eine weitere Anfrage an den API-Endpunkt und fügt die berechnete Antwort in die Anfrage-Header ein.
4. Der Server prüft die Antwort und gewährt, wenn sie korrekt ist, den Zugriff auf die API.

Hinweis: Es ist wichtig, das Sitzungs-Cookie bei jeder nachfolgenden Anfrage mit zu senden.

Hinweis: Die clientseitige Implementierung der NTLM-Authentifizierung muss entweder durch benutzerdefinierten Code oder durch Verwendung von Bibliotheken, die den Authentifizierungsprozess für Sie verwalten können, gehandhabt werden.

Hinweis: Damit die NTLM/Windows-Authentifizierung verwendet werden kann, muss das Plugin aktiviert sein und als Systemauthentifizierungs-Provider verwendet werden.

# First Request
 
# REQUEST
POST /api HTTP/1.1
Authorization: NTLM TlRMTVNTUAABAAAAB7IIogAAAAAAAAAAAAAAAAAAAAAGAbEdAAAADw==
Content-Type: application/json
 
# RESPONSE with actual challenge
HTTP/1.1 401 Unauthorized
WWW-Authenticate: NTLM TlRMTVNTUAACAAAAAAAAACgAAAABggAAU3J2Tm9uY2UAAAAAAAAAAA==
Content-Length: 0
Date: Mon, 14 Feb 2023 06:48:54 GMT

# Secod Request
 
# REQUEST with NTLN response computed by the client based on the challenge
POST /api HTTP/1.1
Authorization: NTLM TlRMTVNTUAADAAAAGAAYAEgAQABQAQAAYAAAABAAEADgAAAA1TSU1BAAAAD05NTUxNTkxM0UyMg==
Content-Type: application/json
 
# RESPONSE
HTTP/1.1 200 OK
Content-Length: ...
Date: Mon, 14 Feb 2023 06:48:55 GMT