🔌 REST-API Schnittstelle

Verbinden Sie externe Systeme und Prozesse nahtlos mit dem E-Coach

Der E-Coach stellt eine umfassende REST-API zur Verfügung, die als Schnittstelle für externe Anwendungen, Automatisierungen und Integrationen dient. Mit dieser API können Sie Drittprogramme anbinden, Daten automatisiert austauschen und individuelle Workflows erstellen.

⚡ Schnellstart

1. Gültigen E-Coach-Benutzer anlegen oder verwenden

2. Bearer-Token über Authentifizierungs-Endpunkt generieren

3. Token in allen API-Anfragen im Header übermitteln

4. Interaktive API-Dokumentation für Tests nutzen: api.ecoach.cloud/swagger

🔒 Sicherheitsmaßnahmen

Die API-Schnittstelle ist durch mehrere Sicherheitsebenen geschützt, um unbefugten Zugriff zu verhindern und die Integrität Ihrer Daten zu gewährleisten.

TLS-Verschlüsselung (HTTPS)

Alle API-Anfragen werden ausschließlich über eine verschlüsselte HTTPS-Verbindung übertragen. Dies gewährleistet, dass sensible Daten wie Zugangsinformationen und Nutzerinhalte während der Übertragung vor unbefugtem Zugriff geschützt sind.

Token-basierte Authentifizierung

Jede Anfrage erfordert einen gültigen Bearer-Token. Dieser wird nach erfolgreicher Authentifizierung mit E-Mail und Passwort generiert und muss bei jeder API-Anfrage im Header mitgesendet werden.

Rate Limiting

Die API verfügt über eine intelligente Limitierung der zulässigen Anfragen pro Zeiteinheit. Dies schützt das System vor Überlastung und Denial-of-Service-Attacken, während normale Nutzungsszenarien problemlos unterstützt werden.

🔑 Authentifizierung

Für die Nutzung der API ist ein gültiger E-Coach-Benutzer erforderlich. Die Rollenzuordnung dieses Benutzers bestimmt, auf welche Endpunkte und Daten die API zugreifen kann.

So funktioniert die Authentifizierung:

1. Senden Sie eine POST-Anfrage an den Auth-Endpunkt mit E-Mail und Passwort

2. Bei erfolgreicher Authentifizierung erhalten Sie einen JSON-Web-Token (JWT)

3. Verwenden Sie diesen Token als Bearer-Token im Authorization-Header aller folgenden Anfragen

4. Nutzen Sie den Refresh-Token, um bei Ablauf einen neuen Access-Token zu erhalten

Beispiel: Token generieren

Anfrage:

curl -X POST "https://api.ecoach.cloud/api/auth" \
  -H "Tenant: <<TENANT>>" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "<<EMAIL>>",
    "password": "<<PASSWORD>>"
  }'

Erfolgreiche Antwort:

{
  "token": "eyJh*****mqBES_8_o",
  "refreshToken": "KYARbBeOEw4+pkAGb7r7HHXjNgZshJlYqGbpVWBi1zo=",
  "refreshTokenExpiryTime": "2025-07-30T10:45:41.4599978Z"
}

Beispiel: Token in API-Anfragen verwenden

Der erhaltene Token muss bei allen nachfolgenden API-Anfragen im Authorization-Header als Bearer-Token übergeben werden:

curl -X GET "https://api.ecoach.cloud/api/users/me" \
  -H "Authorization: Bearer <<TOKEN>>" \
  -H "Content-Type: application/json"

💡 Tipp: Speichern Sie den Token sicher in Ihrer Anwendung und erneuern Sie ihn automatisch über den Refresh-Token, bevor er abläuft. Hardcoden Sie niemals Tokens oder Zugangsdaten direkt in Ihrem Code.

📋 Datenformat

Alle API-Antworten werden im JSON-Format ausgegeben. JSON (JavaScript Object Notation) ist ein leichtgewichtiges, textbasiertes Datenformat, das von nahezu allen modernen Programmiersprachen und Frameworks unterstützt wird.

• Content-Type: application/json

• Zeichenkodierung: UTF-8

• Strukturiert: Klare Hierarchien für einfaches Parsing

🌐 API-Endpunkte & Dokumentation

Die vollständige API-Dokumentation ist interaktiv über Swagger verfügbar. Hier können Sie alle verfügbaren Endpunkte einsehen, Requests testen und Responses direkt im Browser ausprobieren.

🔗 Interaktive API-Dokumentation (Swagger UI)

Nutzen Sie die Swagger-Oberfläche, um alle Endpunkte zu erkunden, Parameter zu verstehen und Anfragen direkt zu testen:

→ https://api.ecoach.cloud/swagger

📥 OpenAPI-Spezifikation herunterladen

Laden Sie die API-Spezifikation als OpenAPI-JSON herunter und importieren Sie sie in Tools wie Postman, Insomnia oder generieren Sie automatisch Client-Code:

→ https://api.ecoach.cloud/swagger/v1/swagger.json

📦 Häufig verwendete API-Funktionen

• Benutzer anlegen, bearbeiten und verwalten

• Teams und Projekte abrufen und zuweisen

• Kurse und Lerninhalte verwalten

• Bewertungen und Fortschritte abfragen

• Benachrichtigungen versenden

• Reports und Statistiken exportieren

💡 Best Practices

Token-Verwaltung

• Speichern Sie Tokens sicher (z.B. in Umgebungsvariablen oder sicheren Vaults)

• Implementieren Sie automatisches Token-Refresh

• Vermeiden Sie Hardcoding von Credentials

Fehlerbehandlung

• Implementieren Sie Retry-Logik für temporäre Fehler

• Prüfen Sie HTTP-Statuscodes und reagieren Sie entsprechend

• Loggen Sie API-Fehler für einfacheres Debugging

Performance

• Nutzen Sie Pagination bei großen Datenmengen

• Cachen Sie häufig abgerufene, statische Daten

• Vermeiden Sie unnötige API-Aufrufe durch intelligentes Batching

Testing & Entwicklung

• Testen Sie neue Integrationen zunächst in der Swagger-UI

• Verwenden Sie Tools wie Postman für strukturierte API-Tests

• Dokumentieren Sie Ihre eigenen API-Workflows

🎯 Typische Anwendungsfälle

→ HR-System-Integration: Automatischer Import neuer Mitarbeiter aus dem HR-System

→ Learning Management: Zuweisung von Kursen basierend auf Jobprofilen

→ Reporting: Automatische Extraktion von Lernfortschritten für Management-Reports

→ Benachrichtigungen: Versand von individualisierten Erinnerungen via externe Systeme

→ Single Sign-On: Integration mit bestehenden Identity-Management-Lösungen

📚 Weiterführende Ressourcen

→ Interaktive API-Dokumentation

→ OpenAPI-Spezifikation (JSON)

→ Benutzerrollen und API-Berechtigungen

Benötigen Sie Unterstützung bei der API-Integration?
Unser technisches Support-Team hilft Ihnen gerne bei der Implementierung!

Verknüpfung mit