# API: Überblick

## Zweck

Übersicht über die Netzwerkschnittstellen. Diese Seite beschreibt grob die Routen, Endpunkte und Services für die Routely-App.

## Wichtige Dateien

- `app/src/main/kotlin/de/traewelling/app/data/api/TraewellingApiService.kt`
- `app/src/main/kotlin/de/traewelling/app/data/api/RetrofitClient.kt`

## TraewellingApiService

Zentrale Schnittstelle, definiert in `TraewellingApiService.kt`. Die App kommuniziert hauptsächlich mit den Träwelling RESTful APIs.

### Wichtigste Endpunkt-Gruppen:

**1. Check-in & Feed (Kernfunktionen)**

- **Check-In**: `POST /api/v1/trains/checkin` – Einchecken in Verkehrsmittel (benötigt Start, Ziel, Fahrt-ID; optional/gesetzt: `business` als Reisegrund).
- **Persönlicher Feed**: `GET /api/v1/dashboard` – Check-ins von Nutzern, denen man folgt.
- **Globaler Feed**: `GET /api/v1/statuses` – Öffentliche Check-ins aller Nutzer.
- **Status (Singular)**: `GET/PUT/DELETE /api/v1/status/{id}` sowie `POST/DELETE /api/v1/status/{id}/like` – Einzelnen Check-in abrufen, ändern, löschen, liken/entliken.

Der persönliche Dashboard-Vertrag verwendet numerische Seiten mit `simplePaginate(15)`. Der globale `statuses`-Controller liefert eine unpaginierte Antwort; die App bietet weitere Seiten nur bei tatsächlich vorhandenem `links.next` an. Ein deklarierter `page`-Parameter macht den globalen Endpunkt nicht automatisch paginiert.

**2. Bahnhöfe & Abfahrten (Reiseplanung)**

- **Station Search**: `GET /api/v1/trains/station/autocomplete/{query}` – Suche von Haltestellen per Text.
- **Stationen in der Nähe**: Der Check-in und die Fahrterkennung verwenden `TraewellingRepository.getNearbyStations(lat, lon)`. Dieser Aufruf berechnet eine ungefähr einen Kilometer in jede Richtung reichende Bounding-Box und sendet `min_lat`, `max_lat`, `min_lon`, `max_lon` an `GET /api/v1/stations`. `GET /api/v1/trains/station/nearby` ist zusätzlich in Retrofit deklariert und liefert einen Bahnhof; die aktuellen App-Abläufe rufen diesen Endpunkt nicht auf.
- **Departures**: `GET /api/v1/station/{id}/departures` – Abfahrtsmonitor. Benötigt die numerische ID, nicht den Namen!
  Die ID ist die interne Träwelling-Station-ID, keine IBNR oder Stopover-ID.

**3. Fahrtdetails & Haltestellen (Trip-Infos)**

- **Trip Detail**: `GET /api/v1/trains/trip` – Liefert den gesamten Fahrtverlauf, benötigt `hafasTripId` und `lineName`.
- **Stopovers**: `GET /api/v1/stopovers/{tripId}` – Detaillierte Route eines getätigten Check-ins.
- **Streckenverlauf**: `GET /api/v1/polyline/{statusId}` – GeoJSON der eigenen eingecheckten Bahn-/Tramstrecke; optionaler Linienzug für lokale GPS-Projektion, kein garantiert amtlicher Fahrweg. Der Status-Identifier ist nicht die Trip-ID.

**4. Benutzer & Authentifizierung**

- **Eigenes Profil**: `GET /api/v1/auth/user` – Eigene Daten abrufen.
- **Fremdes Profil**: `GET /api/v1/user/{username}` – Profil eines anderen Nutzers.
- **Nutzerhistorie**: `GET /api/v1/user/{username}/statuses` – Vergangene Check-ins eines Nutzers.
- **Follow / Unfollow**: `POST/DELETE /api/v1/user/{id}/follow`.

**5. Notifications**

- **Benachrichtigungsliste**: `GET /api/v1/notifications`
- **Ungelesene Zähler**: `GET /api/v1/notifications/unread/count`
- **Gelesen markieren**: `PUT /api/v1/notifications/read/{id}` oder `/all`.

## OAuth

`OAuthApiService` in `TraewellingApiService.kt` deklariert Austausch und Refresh über `POST /oauth/token`. Diese Helfer sind noch nicht an einen erreichbaren Browser-Login oder automatischen Refresh angebunden. Der aktuelle [Anmeldeablauf](../module/auth.md) validiert einen manuell eingegebenen Token mit `GET /api/v1/auth/user` und speichert die Sitzung erst nach einer vollständigen erfolgreichen Antwort.

## Kompatibilitätsstand

Am 05.10.2026 wurden alle vorhandenen Retrofit-Routen und ihre konsumierten Antwortfelder gegen den Träwelling-API-Changelog sowie die Routen und Ressourcen von Upstream `develop` geprüft. Die vorhandenen Pfade bleiben gültig; die notwendigen Änderungen betreffen insbesondere Stationsdaten in Stopovers, Zeitfelder, Operator-IDs und Check-in-Konflikte.

Die [Kompatibilitätsprüfung](./traewelling-kompatibilitaet.md) dokumentiert den geprüften Upstream-Commit, die Migration und bewusst ungenutzte neue APIs. Neue optionale Endpunkte ersetzen nicht automatisch die bestehenden App-Funktionen.

## Logging und Tokens

`RetrofitClient` setzt den Bearer-Token als `Authorization`-Header. Netzwerk-Logging ist im Release-Build deaktiviert und im Debug-Build auf `BASIC` begrenzt; `Authorization` wird redaktiert.

## Verwandte Seiten

- [Interne Schnittstellen](./interne-schnittstellen.md)
- [Externe Schnittstellen](./externe-schnittstellen.md)
- [Träwelling-API-Kompatibilität](./traewelling-kompatibilitaet.md)
- [Check-in](../module/checkin.md)
- [Secrets und Sicherheit](../konfiguration/secrets-und-sicherheit.md)