Quelltext der Seite DriversHub

# Drivers Hub Backend – 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:

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

Damit lautet die Base URL:

```text
https://hub.example.com/api
```

Ein Request auf:

```text
GET /user/profile
```

wird also beispielsweise:

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

Der Prefix ist konfigurierbar und muss mit `/` beginnen.

### Swagger / OpenAPI

Wenn in der Konfiguration

```json
{
  "openapi": true
}
```

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

```text
{prefix}/doc
```

bereit.

Bei `prefix: "/api"` also:

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

Im Repository liegt außerdem:

```text
/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:

```http
Authorization: Bearer <TOKEN>
```

Beispiel:

```bash
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:

```http
Authorization: Application <TOKEN>
```

Beispiel:

```bash
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:

```http
Content-Type: application/json
```

Ausnahmen sind insbesondere Tracker-Webhooks:

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

Diese dürfen tracker-spezifische Payloads verwenden.

Standard-JSON-Request:

```bash
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:

```json
{
  "error": "Fehlermeldung"
}
```

Typische Statuscodes sind:

```text
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:

```json
{
  "error": "Unprocessable Entity"
}
```

ersetzt.

---

# 4. Rate Limits

Es gibt globale und endpoint-spezifische Rate Limits.

Global:

```text
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`:

```text
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:

```text
uid
```

oder

```text
userid
```

verlangen.

---

# 6. Login und Authentifizierungsflow

## POST `/auth/password`

Login mit E-Mail und Passwort.

### Body

```json
{
  "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:

```text
Cloudflare Turnstile
hCaptcha
```

### Erfolgreicher Login ohne MFA

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

### Login mit aktiviertem MFA

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

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

Danach:

```http
POST /auth/mfa
```

Body:

```json
{
  "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:

```json
{
  "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:

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

---

## POST `/auth/reset`

Startet einen Password-Reset.

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

---

## POST `/auth/email`

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

Query:

```text
?secret=<SECRET>
```

Bei Password-Reset ggf. Body:

```json
{
  "password": "NewSecret123!"
}
```

---

## Discord / Steam Login

### GET `/auth/discord/callback`

Queryparameter:

```text
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:

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

Tokenliste unterstützt unter anderem:

```text
page
page_size
order_by
order
```

Mögliche `order_by`-Werte laut OpenAPI:

```text
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:

```text
userid
uid
discordid
steamid
truckersmpid
email
```

Zusätzliche Parameter:

```text
role_history_limit
ban_history_limit
```

Ohne Ziel-ID wird typischerweise das eigene Profil verwendet.

Beispiel:

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

Oder:

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

### PATCH `/user/profile`

Body:

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

Optionale Queryparameter:

```text
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:

```text
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

```text
POST /custom-tracker/update
```

## UniTracker

```text
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

```text
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.:

```text
page
page_size
order_by
order
```

`order_by` kann beispielsweise:

```text
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:

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

---

# 27. Beispiel eines kompletten Clients

Shell-Setup:

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

## Status

```bash
curl -sS "$BASE/status"
```

## Login

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

Response:

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

## Eigenes Profil

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

## Fremdes Profil anhand UID

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

## Profil ändern

```bash
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

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

## Token prüfen

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

## Logout / Token widerrufen

```bash
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:

```text
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:

```json
"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:

```json
"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:

```text
/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:

```text
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:

```text
/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

```text
/                         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
```