Integration: REST API
Die eTASK REST-API ist die zentrale programmatische Schnittstelle für den Zugriff auf eTASK-Daten durch Drittsysteme. Sie basiert auf JSON über HTTPS und folgt der OpenAPI-Spezifikation.
Voraussetzungen
- Administratorrechte im eTASK-Portal
- TLS-Verbindung – Die API erfordert HTTPS
- API-Token – Für den authentifizierten Zugriff auf die API
Schritt 1: API-Rechte prüfen
Pfad zum Ausgangspunkt: Systemsteuerung → Rechteverwaltung → API-Rechte je Gruppe
Diese Auswertung gibt einen detaillierten Überblick, welche Rechtegruppen Zugriff haben auf welche API-Endpunkte und mit welchen Rechten. Beachten Sie besonders die Spalte „Std. Gruppe", da jeder angemeldete Anwender im Portal automatisch die Rechte dieser Gruppe erbt.
| Feld | Beschreibung |
|---|---|
| API Gruppe | Hier sehen Sie den Hauptpunkt im API, unter dem diese Route gelistet wird. |
| API | Hier können Sie das API ablesen, zu dem dieser Endpunkt gehört. |
| Endpoint | Hier sehen Sie den Namen des Endpunktes. |
| Pattern | An dieser Stelle können Sie das Pattern für den API-Aufruf erkennen. |
| Gruppe Code | Hier sehen Sie die Kurzbezeichnung der Rechtegruppe. |
| Benutzergruppe | Hier steht der Name der Benutzergruppe. |
| Std. Gruppe | Hier können Sie erkennen, ob diese Gruppe als Standardgruppe definiert ist und damit alle Rechte in der Gruppe an alle Portalnutzer vererbt werden, ohne dass sie explizit der Gruppe zugeordnet sind. |
Schritt 2: API-Token verwalten
Pfad zum Ausgangspunkt: Systemsteuerung → Portal-Optionen → Schnittstellen → Schnittstellenkonfiguration → Webservice API → Secure (OAuth)
Übersicht aller ausgestellten API-Tokens.
Infobereich „Identifikation"
| Feld | Beschreibung |
|---|---|
| Benutzer | Name des Benutzers, auf den der Token registriert bzw. ausgestellt wurde. Alle Abfragen erfolgen im Kontext dieses Benutzers. |
| API Token | Das Token wird automatisch beim Speichern generiert. |
| Gültig ab | Datum, ab dem der API-Token gültig ist. |
| Gültig bis | Datum, bis zu dem der API-Token gültig ist (inkl. des letzten Tags). |
| Ausstellungsdatum | Wann der Token ausgestellt wurde. |
Infobereich „Scopes"
Jedem Token können Scopes zugeordnet werden, um den Zugriff auf bestimmte API-Bereiche einzuschränken.
Schritt 3: CORS konfigurieren
Pfad zum Ausgangspunkt: Systemsteuerung → Portal-Optionen → Schnittstellen → CORS → Origins
In dieser Liste können Sie Quellsysteme hinterlegen, für die Sie Cross-Origin-Anfragen erlauben möchten. eTASK wird benötigte Quellen während der Installation anlegen.
| Feld | Beschreibung |
|---|---|
| Quelle | Geben Sie hier die Quelle an, von der aus Sie Cross-Origin-Anfragen erlauben möchten. |
Schritt 4: API-Nutzung überwachen
Pfad zum Ausgangspunkt: Systemsteuerung → Portal-Verwaltung → Portal-Wartung → Nutzungsstatistik API-Abruf
Aus dieser Auswertung können Sie ablesen, welche Ihrer bereitgestellten API-Routen genutzt werden, und mit welchem Benutzer diese wie oft aufgerufen wurden. Zusätzlich können Sie noch die eTASK-Version erkennen, in der dies passiert. Nutzen Sie diese Information, um zu überwachen, wo das API verwendet wird und die zentralen Nutzungsstellen zu identifizieren.
| Feld | Beschreibung |
|---|---|
| URL | Gibt die Adresse wieder, unter der dieser Eintrag der Nutzungsstatistik erzeugt wurde. |
| API-Version | Mit dieser Version wurde der Eintrag geschrieben. Die Anzahl wird je API-Endpunkt und Version summiert. |
| Route | Für diese Route im API wurde der Zugriff gezählt. |
| Anzahl Aufrufe | Die Anzahl der Aufrufe wird je Endpunkt und API-Version summiert. |
Schritt 5: OpenAPI-Dokumentation nutzen
Die vollständige API-Dokumentation ist unter folgender URL erreichbar:
https://<Ihre-Instanz>/API/openapi/docs/index.html
Dort finden Sie:
- Alle verfügbaren Endpunkte mit Request-/Response-Beispielen
- Die OpenAPI 3.0 Spezifikation zum Download
- Möglichkeit zum direkten Testen der Endpunkte
Systemparameter
Pfad zum Ausgangspunkt: Systemsteuerung → Portal-Optionen → Konfigurationsparameter
Die folgenden Systemparameter sind für die REST-API-Integration relevant. Sie steuern den CSRF-Schutz und die Zertifikatsbehandlung bei der Kommunikation mit externen Systemen.
| Parameter | Beschreibung | Standardwert |
|---|---|---|
| ANTICROSSSITEREQUESTFORGERY | Aktiviert den CSRF-Schutz (Cross-Site Request Forgery) für das Portal. Bei Wert 1 werden nur Anfragen von vertrauenswürdigen Quellen akzeptiert. Stellen Sie sicher, dass alle externen Systeme, die auf die API zugreifen, in ALLOWEDREFERERS hinterlegt sind. |
0 (deaktiviert) |
| ALLOWEDREFERERS | Kommagetrennte Liste vertrauenswürdiger Domains, die bei aktiviertem CSRF-Schutz erlaubt sind. Tragen Sie hier die URLs aller externen Anwendungen ein, die über die REST-API auf das Portal zugreifen (z. B. https://meine-app.firma.de). |
(leer) |
| ALLOWCERTIFICATEERROR | Steuert, ob SSL-Zertifikatfehler bei Verbindungen zu externen Diensten toleriert werden. Wert 1 toleriert Fehler (nur für Testzwecke), Wert 0 erzwingt gültige Zertifikate (empfohlen für Produktionsumgebungen). |
0 (deaktiviert) |