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 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.

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 Vorschaumodus 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, der dann entscheiden kann, das Ausführen eines bestimmten Befehls nur zu simulieren.

Ob ein Befehl mit tatsächlichen Daten im Vorschaumodus ausgeführt wird, hängt stark vom jeweiligen Befehl ab. Normalerweise ist der Vorschaumodus 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.

Anfragen an die Web-API erfordern eine ordnungsgemäße Authentifizierung. Viele der vorinstallierten Authentifizierungsanbieter unterstützen das BASIC-Authentifizierungsschema.

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

Jede Sitzung verbraucht Speicher und verlangsamt den Server.

Bei Verwendung des BASIC-Authentifizierungsschemas wird eine Sitzung erstellt, und es ist wichtig, diese Sitzung für nachfolgende Anfragen wiederzuverwenden. Andernfalls können sich unnötige Sitzungen ansammeln, was den Server verlangsamen kann. Um dies zu verhindern, steht ein zusätzliches Defender Plugin zur Verfügung, das die Anzahl der innerhalb eines bestimmten Zeitraums erstellten Sitzungen begrenzt und bei Überschreitung den Benutzer und die IP für die Anmeldung sperrt.

Lösung: Um die Erstellung unnötiger Sitzungen zu vermeiden, können Sie entweder die Sitzung wiederverwenden, indem Sie das Sitzungs-Cookie mit jeder Anfrage senden, oder das Token-Authentifizierungs-Plugin verwenden. Mit dem Token-Authentifizierungs-Plugin meldet sich der Benutzer bei jeder Anfrage an, ohne eine Sitzung zu erstellen, wodurch die Anfragen zustandslos werden.

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

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.