Suche aufrufen
Menü aufrufen
Kosmos MediaWiki
Toggle preferences menu
Persönliches Menü aufrufen
Nicht angemeldet
Ihre IP-Adresse wird öffentlich sichtbar sein, wenn Sie Änderungen vornehmen.

DriversHub

Aus Kosmos MediaWiki
Weitere Optionen
Version vom 18. August 2026, 21:52 Uhr von Kosmos (Diskussion | Beiträge)
(Unterschied) ← Nächstältere Version | Aktuelle Version (Unterschied) | Nächstjüngere Version → (Unterschied)

API-Dokumentation

Repository: CharlesWithC/HubBackend

1. API-Grundlagen

Base URL

Die API besitzt keine fest eingebaute öffentliche Base URL. Host und API-Prefix kommen aus der Hub-Konfiguration.

Beispielkonfiguration: 

{
  "domain": "hub.example.com",
  "prefix": "/api"
}

Damit lautet die Base URL: 

https://hub.example.com/api

Ein Request auf: 

GET /user/profile

wird also beispielsweise: 

GET https://hub.example.com/api/user/profile

Der Prefix ist konfigurierbar und muss mit / beginnen.

Swagger / OpenAPI

Wenn in der Konfiguration 

{
  "openapi": true
}

gesetzt wird, stellt der Server die interaktive Swagger-Dokumentation unter 

{prefix}/doc

bereit.

Bei prefix: "/api" also: 

https://hub.example.com/api/doc

Im Repository liegt außerdem: 

/openapi.json

2. Authentifizierung

Es gibt zwei Token-Typen:

  1. Bearer Token – für Benutzer
  2. Application Token – für Anwendungen/Integrationen

Bearer Token

Header: 

Authorization: Bearer <TOKEN>

Beispiel: 

curl \
  -H "Authorization: Bearer e1234567-89ab-cdef-0123-456789abcdef" \
  https://hub.example.com/api/user/profile

Tokens sind UUID-artige, serverseitig gespeicherte Session-Tokens. Es steckt kein JWT-Payload darin.

Application Token

Header: 

Authorization: Application <TOKEN>

Beispiel: 

curl \
  -H "Authorization: Application 12345678-1234-1234-1234-123456789abc" \
  https://hub.example.com/api/user/profile

Application Tokens haben gegenüber normalen User-Tokens Einschränkungen. Nicht jeder authentifizierte Endpoint muss Application Tokens akzeptieren.

3. Allgemeine Request-Regeln

Für praktisch alle Requests außer GET erwartet das Backend: 

Content-Type: application/json

Ausnahmen sind insbesondere Tracker-Webhooks: 

/tracksim/*
/trucky/*
/custom-tracker/*
/unitracker/*

Diese dürfen tracker-spezifische Payloads verwenden.

Standard-JSON-Request: 

curl -X PATCH \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"John Doe"}' \
  "$BASE/user/profile"

Fehlerformat

FastAPI-/HTTP-Fehler werden grundsätzlich in dieser Art zurückgegeben: 

{
  "error": "Fehlermeldung"
}

Typische Statuscodes sind: 

400  Bad Request
401  Unauthorized
403  Forbidden
404  Not Found
409  Conflict
422  Unprocessable Entity
423  Locked
428  Precondition Required
429  Too Many Requests
500  Internal Server Error
503  Service Unavailable

Bei Request-Validation wird die normale ausführliche FastAPI-422-Antwort durch: 

{
  "error": "Unprocessable Entity"
}

ersetzt.

4. Rate Limits

Es gibt globale und endpoint-spezifische Rate Limits.

Global: 

300 Requests / 60 Sekunden

Nach Überschreiten kann der Client für etwa fünf Minuten global blockiert werden.

Zusätzlich besitzen einzelne Endpoints eigene Limits.

Beispiel aus /auth/password: 

3 Requests / 60 Sekunden

5. Benutzer-IDs: uid vs. userid

Das ist für Clients besonders wichtig.

uid

Interne, eindeutige User-ID.

Jeder Account besitzt eine uid.

userid

Mitglieds-/Driver-Hub-ID.

Diese existiert erst sinnvoll, nachdem ein Account als Mitglied angenommen wurde.

Daher können APIs je nach Einsatzzweck entweder: 

uid

oder 

userid

verlangen.

6. Login und Authentifizierungsflow

POST /auth/password

Login mit E-Mail und Passwort.

Body

{
  "email": "user@example.com",
  "password": "Secret123!",
  "captcha-response": "<captcha-token>"
}

captcha-response sollte als erforderlich betrachtet werden, auch wenn die OpenAPI-Datei es nicht sauber als required kennzeichnet.

Unterstützte Captcha-Systeme: 

Cloudflare Turnstile
hCaptcha

Erfolgreicher Login ohne MFA

{
  "token": "e....",
  "mfa": false
}

Login mit aktiviertem MFA

{
  "token": "f....",
  "mfa": true
}

Der zurückgegebene Token ist in diesem Fall zunächst ein temporäres Auth-Ticket.

Danach: 

POST /auth/mfa

Body: 

{
  "token": "<temporary-auth-ticket>",
  "otp": "123456"
}

Danach erhält man den eigentlichen Session-Token.

POST /auth/register

Registriert einen Account per E-Mail/Passwort.

Body: 

{
  "email": "user@example.com",
  "password": "Secret123!",
  "captcha-response": "<captcha-token>"
}

Das Passwort muss mindestens acht Zeichen lang sein. Die konkrete Prüfung berücksichtigt außerdem Groß-/Kleinbuchstaben, Zahlen und Sonderzeichen.

Eine funktionierende SMTP-Konfiguration ist für die E-Mail-Bestätigung notwendig.

Bei Erfolg wird bereits ein Session-Token ausgegeben: 

{
  "token": "e....",
  "mfa": false
}

POST /auth/reset

Startet einen Password-Reset. 

{
  "email": "user@example.com",
  "captcha-response": "<captcha-token>"
}

POST /auth/email

Verarbeitet E-Mail-Bestätigungs-/Reset-Links.

Query: 

?secret=<SECRET>

Bei Password-Reset ggf. Body: 

{
  "password": "NewSecret123!"
}

Discord / Steam Login

GET /auth/discord/callback

Queryparameter: 

code
error_description
callback_url

callback_url ist erforderlich.

GET /auth/steam/callback

Steam-OpenID-Callback.

Die von Steam gelieferten Parameter müssen an diesen Endpoint weitergereicht werden.

7. Token API

Method Endpoint Funktion
GET /token aktuellen Token validieren
PATCH /token aktuellen Token erneuern
DELETE /token aktuellen Token widerrufen
GET /token/list Sessions/Tokens auflisten
DELETE /token/hash bestimmten Token anhand Hash widerrufen
DELETE /token/all alle Benutzer-Tokens widerrufen
GET /token/application/list Application Tokens auflisten
POST /token/application Application Token erzeugen
DELETE /token/application Application Token widerrufen
DELETE /token/application/all alle Application Tokens widerrufen
POST /auth/ticket Auth-Ticket erzeugen/verwenden
GET /auth/ticket Auth-Ticket abrufen

Beispiel Token-Validierung: 

curl \
  -H "Authorization: Bearer $TOKEN" \
  "$BASE/token"

Tokenliste unterstützt unter anderem: 

page
page_size
order_by
order

Mögliche order_by-Werte laut OpenAPI: 

ip
timestamp
country_code
user_agent
last_used_timestamp

8. System-/Info-API

Method Endpoint Funktion
GET / Drivers-Hub-Informationen
GET /status Serverstatus
POST /status/database/restart Datenbankverbindung neu starten
GET /languages Hub- und unterstützte Sprachen
POST /discord/role-connection/enable Discord Role Connection aktivieren
POST /discord/role-connection/disable Discord Role Connection deaktivieren
GET /config Konfiguration lesen
PATCH /config Konfiguration ändern
POST /config/reload Konfiguration neu laden
POST /restart Backend neu starten
GET /audit/list Audit-Log abrufen

Administrative Endpoints sind entsprechend permission-geschützt.

9. User API

Profile und Benutzer

Method Endpoint Funktion
GET /user/list Benutzerliste
GET /user/profile Userprofil abrufen
PATCH /user/profile Name/Avatar ändern
PATCH /user/bio Bio ändern
PATCH /user/activity Aktivitätsdaten ändern
PATCH /user/{uid}/note persönliche Notiz über User
PATCH /user/{uid}/note/global globale Staff-Notiz
POST /user/tracker/switch aktiven Tracker wechseln

GET /user/profile

Kann einen Benutzer anhand verschiedener IDs suchen: 

userid
uid
discordid
steamid
truckersmpid
email

Zusätzliche Parameter: 

role_history_limit
ban_history_limit

Ohne Ziel-ID wird typischerweise das eigene Profil verwendet.

Beispiel: 

curl \
  -H "Authorization: Bearer $TOKEN" \
  "$BASE/user/profile?uid=123"

Oder: 

curl \
  -H "Authorization: Bearer $TOKEN" \
  "$BASE/user/profile?discordid=123456789012345678"

PATCH /user/profile

Body: 

{
  "name": "New Name",
  "avatar": "https://example.com/avatar.png"
}

Optionale Queryparameter: 

uid
sync_from_discord
sync_from_steam
sync_from_truckersmp

Damit können Profildaten auch von verbundenen Plattformen synchronisiert werden.

10. Sprache, Zeitzone und Privacy

Method Endpoint Funktion
GET /user/language aktuelle Sprache
PATCH /user/language Sprache ändern
GET /user/timezone Zeitzone lesen
PATCH /user/timezone Zeitzone ändern
GET /user/privacy Privacy-Einstellungen
PATCH /user/privacy Privacy-Einstellungen ändern

11. Password und MFA

Method Endpoint Funktion
PATCH /user/password Passwort ändern
POST /user/password/disable Password-Login deaktivieren
POST /user/mfa/enable TOTP-MFA aktivieren
POST /user/mfa/disable MFA deaktivieren

TOTP-MFA wird bei jedem Login verwendet.

Für besonders kritische administrative Aktionen, insbesondere Config-Reload, kann MFA verpflichtend sein.

12. User Connections

Method Endpoint Funktion
POST /user/resend-confirmation Bestätigungsmail erneut senden
PATCH /user/email E-Mail verbinden/ändern
PATCH /user/discord Discord verbinden
PATCH /user/steam Steam verbinden
PATCH /user/truckersmp TruckersMP verbinden
PATCH /user/{uid}/connections Connections administrativ ändern
DELETE /user/{uid}/connections/{connection} Connection entfernen

Für das Job-Tracking ist insbesondere eine verbundene Steam-ID relevant.

13. Notifications

Method Endpoint Funktion
GET /user/notification/list Notifications auflisten
GET /user/notification/{notificationid} Notification lesen
DELETE /user/notification Notification(s) löschen
PATCH /user/notification/{notificationid}/status/{status} Status ändern
GET /user/notification/settings Notification Settings
POST /user/notification/settings/{notification_type}/enable Typ aktivieren
POST /user/notification/settings/{notification_type}/disable Typ deaktivieren

14. User Administration / Bans

Method Endpoint Funktion
POST /user/{uid}/accept Benutzer als Mitglied akzeptieren
DELETE /user/{uid} Benutzer löschen
GET /user/ban/list Bannliste
GET /user/ban Banninformationen
PUT /user/ban Bann erstellen
DELETE /user/ban Bann entfernen
DELETE /user/ban/history/{historyid} Bann-History-Eintrag löschen

Das „Akzeptieren“ eines Users ist unabhängig vom Application-Plugin.

15. Member API

Informationen

Method Endpoint Funktion
GET /member/roles Rollen
GET /member/ranks Ranks
GET /member/perms Permissions
GET /member/list Mitgliederliste
GET /member/banner Mitgliederbanner

Eigene Member-Aktionen

Method Endpoint Funktion
PATCH /member/roles/rank Default Rank-Rolle ändern
PATCH /member/roles/rank/{rank_type_id} Rank-Rolle bestimmten Typs ändern
GET /member/bonus/history Bonus-History
POST /member/bonus/claim Bonus beanspruchen
GET /member/bonus/notification/settings Bonus-Notification-Settings
PATCH /member/bonus/notification/settings Settings ändern
DELETE /member/roles/history/{historyid} Rollen-History löschen
POST /member/resign Mitgliedschaft niederlegen

Member Administration

Method Endpoint Funktion
PATCH /member/{userid}/roles Rollen ändern
PATCH /member/{userid}/points Punkte ändern
POST /member/{userid}/dismiss Mitglied entlassen

16. Driving Logs – /dlog

Method Endpoint Funktion
GET /dlog/list Fahrten auflisten
GET /dlog/{logid} einzelne Fahrt
DELETE /dlog/{logid} Fahrt löschen
GET /dlog/leaderboard Leaderboard
GET /dlog/export Fahrten exportieren
GET /dlog/statistics/summary aggregierte Statistik
GET /dlog/statistics/chart Chart-Daten
GET /dlog/statistics/details Detailstatistik

Diese APIs gehören zu den mächtigeren Teilen des Backends und besitzen zahlreiche Filter für beispielsweise: 

Fahrer
Zeiträume
Distanz
Einnahmen
Schaden
Fahrzeug
Fracht
Start-/Zielort
Spiel
Tracker

Die Filter sollten anhand der jeweiligen OpenAPI-Definition verwendet werden, da die Statistik-Endpoints unterschiedlich große Parametersätze besitzen.

17. Tracker APIs

Tracker-Routen werden nur aktiviert, wenn der entsprechende Tracker konfiguriert ist.

TrackSim

Method Endpoint
POST /tracksim/update
POST /tracksim/update/route
PUT /tracksim/driver/{userid}
DELETE /tracksim/driver/{userid}

Trucky

Method Endpoint
POST /trucky/update
POST /trucky/import/{jobid}
PUT /trucky/driver/{userid}
DELETE /trucky/driver/{userid}

Custom Tracker

POST /custom-tracker/update

UniTracker

POST /unitracker/update

Diese Endpoints sind primär für Tracker-Server/Webhooks gedacht, nicht für den normalen Browser-Client.

18. Announcements Plugin

Nur vorhanden, wenn das Plugin aktiviert ist.

Method Endpoint Funktion
GET /announcements/types Announcement-Typen
GET /announcements/list Liste
GET /announcements/{announcementid} Eintrag
POST /announcements erstellen
PATCH /announcements/{announcementid} ändern
DELETE /announcements/{announcementid} löschen

19. Applications Plugin

Method Endpoint Funktion
GET /applications/types Application-Typen
GET /applications/list Bewerbungen
GET /applications/statistics Statistiken
GET /applications/{applicationid} Bewerbung
POST /applications Bewerbung erstellen
POST /applications/{applicationid}/message Nachricht hinzufügen
PATCH /applications/{applicationid}/status Status ändern
DELETE /applications/{applicationid} löschen

Hinweis: Das Akzeptieren einer Application akzeptiert den User nicht automatisch als Hub-Mitglied.

20. Challenges Plugin

Method Endpoint
GET /challenges/list
GET /challenges/{challengeid}
POST /challenges
PATCH /challenges/{challengeid}
DELETE /challenges/{challengeid}
PUT /challenges/{challengeid}/delivery/{logid}
DELETE /challenges/{challengeid}/delivery/{logid}

Die letzten beiden Calls ordnen Driving Logs einer Challenge zu bzw. entfernen sie.

21. Divisions Plugin

Method Endpoint
GET /divisions/list
GET /divisions/statistics
GET /divisions/{divisionid}/activity
GET /divisions/list/pending
GET /dlog/{logid}/division
POST /dlog/{logid}/division/{divisionid}
PATCH /dlog/{logid}/division/{divisionid}

22. Downloads Plugin

Method Endpoint
GET /downloads/list
GET /downloads/redirect/{secret}
GET /downloads/{downloadsid}
POST /downloads
PATCH /downloads/{downloadsid}
DELETE /downloads/{downloadsid}

/downloads/redirect/{secret} dient dem kontrollierten Download/Redirect anhand eines Secrets.

23. Economy Plugin

Das Economy-Plugin besitzt eine umfangreiche eigene API.

Economy Overview

GET /economy

Balance

Method Endpoint
GET /economy/balance
GET /economy/balance/{userid}
PATCH /economy/balance/{userid}
GET /economy/balance/leaderboard
POST /economy/balance/transfer
GET /economy/balance/{userid}/transactions/list
GET /economy/balance/{userid}/transactions/export
POST /economy/balance/{userid}/visibility/{visibility}

Garages

Method Endpoint
GET /economy/garages
GET /economy/garages/list
GET /economy/garages/{garageid}
POST /economy/garages/{garageid}/purchase
POST /economy/garages/{garageid}/transfer
POST /economy/garages/{garageid}/sell

Garage Slots

Method Endpoint
GET /economy/garages/{garageid}/slots/list
GET /economy/garages/{garageid}/slots/{slotid}
POST /economy/garages/{garageid}/slots/purchase
POST /economy/garages/{garageid}/slots/{slotid}/transfer
POST /economy/garages/{garageid}/slots/{slotid}/sell

Trucks

Method Endpoint
GET /economy/trucks
GET /economy/trucks/list
GET /economy/trucks/{vehicleid}
GET /economy/trucks/{vehicleid}/{operation}/history
POST /economy/trucks/{truckid}/purchase
POST /economy/trucks/{vehicleid}/transfer
POST /economy/trucks/{vehicleid}/relocate
POST /economy/trucks/{vehicleid}/activate
POST /economy/trucks/{vehicleid}/deactivate
POST /economy/trucks/{vehicleid}/repair
POST /economy/trucks/{vehicleid}/sell
POST /economy/trucks/{vehicleid}/scrap

Merchandise

Method Endpoint
GET /economy/merch
GET /economy/merch/list
POST /economy/merch/{merchid}/purchase
POST /economy/merch/{itemid}/transfer
POST /economy/merch/{itemid}/sell

24. Events Plugin

Method Endpoint
GET /events/list
GET /events/{eventid}
PUT /events/{eventid}/vote
DELETE /events/{eventid}/vote
POST /events
PATCH /events/{eventid}
DELETE /events/{eventid}
PATCH /events/{eventid}/attendees

Beim Bearbeiten von Attendees werden User-IDs verwendet.

25. Poll Plugin

Method Endpoint
GET /polls/list
GET /polls/{pollid}
PUT /polls/{pollid}/vote
PATCH /polls/{pollid}/vote
DELETE /polls/{pollid}/vote
POST /polls
PATCH /polls/{pollid}
DELETE /polls/{pollid}

GET /polls/list unterstützt u. a.: 

page
page_size
order_by
order

order_by kann beispielsweise: 

orderid
pollid
title
timestamp
end_time

sein.

26. Tasks Plugin

Method Endpoint
GET /tasks/list
GET /tasks/{taskid}
POST /tasks
PATCH /tasks/{taskid}
DELETE /tasks/{taskid}
PUT /tasks/{taskid}/complete/mark
DELETE /tasks/{taskid}/complete/mark
POST /tasks/{taskid}/complete/accept
POST /tasks/{taskid}/complete/reject

Der typische Workflow ist: 

Task erstellen
      ↓
User markiert Task als erledigt
      ↓
Staff akzeptiert oder verwirft die Completion

27. Beispiel eines kompletten Clients

Shell-Setup: 

BASE="https://hub.example.com/api"
TOKEN="..."

Status

curl -sS "$BASE/status"

Login

curl -sS \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "Secret123!",
    "captcha-response": "CAPTCHA_TOKEN"
  }' \
  "$BASE/auth/password"

Response: 

{
  "token": "e1234567-89ab-cdef-0123-456789abcdef",
  "mfa": false
}

Eigenes Profil

curl -sS \
  -H "Authorization: Bearer $TOKEN" \
  "$BASE/user/profile"

Fremdes Profil anhand UID

curl -sS \
  -H "Authorization: Bearer $TOKEN" \
  "$BASE/user/profile?uid=42"

Profil ändern

curl -sS \
  -X PATCH \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Kosmos",
    "avatar": "https://example.com/avatar.png"
  }' \
  "$BASE/user/profile"

Driving Logs

curl -sS \
  -H "Authorization: Bearer $TOKEN" \
  "$BASE/dlog/list?page=1&page_size=50"

Token prüfen

curl -sS \
  -H "Authorization: Bearer $TOKEN" \
  "$BASE/token"

Logout / Token widerrufen

curl -sS \
  -X DELETE \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  "$BASE/token"

28. Wichtige Besonderheiten für Client-Entwickler

1. Nicht alle Endpoints sind immer vorhanden

Tracker-Endpunkte hängen von den konfigurierten Trackern ab.

Plugin-Endpunkte hängen von den aktivierten Plugins ab.

Ein 404 Not Found kann daher bedeuten, dass die entsprechende Funktion im aktuellen Hub deaktiviert ist.

2. Permissions sind dynamisch

Viele Endpoints verlangen keine fest im Endpointnamen sichtbare Rolle wie admin.

Die Autorisierung basiert auf: 

User accepted?
+
Roles
+
Permissions der Rollen

Ein Benutzer muss mindestens eine passende Permission besitzen.

3. Application Token != User Token

Ein Application Token wird vom System ausdrücklich anders behandelt.

Ein Client sollte daher nicht davon ausgehen, dass jeder Bearer-Endpunkt automatisch mit Application Token funktioniert.

4. OpenAPI beschreibt Responses kaum

Viele Definitionen enthalten: 

"responses": {}

Für einen streng typisierten Client sollte man Response-Schemas daher aus der Implementierung bzw. aus echten Testantworten ableiten.

5. Captcha-Abweichung

Bei /auth/password, /auth/register und /auth/reset sollte der Client immer: 

"captcha-response": "..."

mitsenden.

Zumindest beim Password-Login greift die Implementierung direkt auf dieses Feld zu.

6. API-Versionierung

Die API verwendet keine Versionsnummer im URL-Pfad wie: 

/api/v1/...

Die Kompatibilität hängt daher von der eingesetzten HubBackend-Version ab.

29. Empfehlung für eine eigene Integration

Für einen normalen Web-/Desktop-Client würde ich folgende Reihenfolge verwenden: 

GET /
   ↓
GET /languages
   ↓
POST /auth/password
   ↓
optional POST /auth/mfa
   ↓
GET /token
   ↓
GET /user/profile
   ↓
GET /member/perms
   ↓
Features abhängig von Permissions anzeigen

Danach können beispielsweise: 

/dlog/*
/member/*
/announcements/*
/applications/*
/events/*
/economy/*

verwendet werden.

Für einen generischen Client ist es sinnvoll, nicht hart anzunehmen, welche Plugins vorhanden sind, sondern die Hub-Konfiguration bzw. verfügbaren Funktionen beim Start festzustellen.

30. Kurzreferenz der API-Bereiche

/                         Server/Hub Info
/status                   Status
/config                   Administration
/audit                    Audit Log

/auth/*                   Login / Registration
/token/*                  Sessions / Application Tokens

/user/*                   Accounts
/member/*                 Mitglieder / Rollen / Punkte
/dlog/*                   Driving Logs & Statistiken

/tracksim/*               TrackSim
/trucky/*                 Trucky
/custom-tracker/*         Custom Tracker
/unitracker/*             UniTracker

/announcements/*          Announcements Plugin
/applications/*           Applications Plugin
/challenges/*             Challenge Plugin
/divisions/*              Division Plugin
/downloads/*              Downloads Plugin
/economy/*                Economy Plugin
/events/*                 Event Plugin
/polls/*                  Poll Plugin
/tasks/*                  Task Plugin
Abgerufen von „https://wiki.kosmos.ac/index.php?title=DriversHub&oldid=3“
Inhaltsverzeichnis