Skip to content

ueberblick

Jump to bottom
Actionbot edited this page Oct 6, 2026 · 9 revisions

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

Clone this wiki locally