REST-API

Programmatischer Zugriff auf deine Streckenkunde-Daten per JSON-API.

Die vollständige, interaktive API-Referenz mit allen Endpunkten, Parametern und Schemas findest du unter /api/docs (Login erforderlich).

Überblick

Die Streckenkunde Digital API basiert auf API Platform und nutzt das JSON-LD-Format. Die Authentifizierung erfolgt über JWT (JSON Web Tokens). Alle Daten sind nutzerbezogen - du siehst ausschließlich deine eigenen Strecken, Touren, Fahrzeuge und Dokumentationen.

Basis-URL

https://streckenkunde.digital/api

Formate

Standardformat: application/ld+json (JSON-LD). Alternativ: application/json.

Authentifizierung

Die API ist zustandslos (stateless). Jede Anfrage muss ein gültiges JWT im Authorization-Header enthalten.

JWT-Token anfordern

Sende deine Zugangsdaten an den Login-Endpunkt:

POST /api/login

Content-Type: application/json

{
  "email": "deine@email.de",
  "password": "dein-passwort"
}

Antwort bei Erfolg:

{
  "token": "eyJ0eXAiOiJKV1QiLCJhbGciOi..."
}

Token verwenden
Setze das Token als Bearer-Token in den Authorization-Header:
```
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOi...
```

Das Token ist 1 Stunde gültig. Nach Ablauf muss ein neues Token über /api/login angefordert werden. Es gibt ein Rate-Limit von 10 Login-Versuchen pro 15 Minuten.

Verfügbare Ressourcen

Die API stellt folgende Ressourcen bereit. Alle Ressourcen sind auf deinen Nutzer beschränkt (Owner Scoping).

Ressource	Beschreibung	Operationen
`/api/routes`	Strecken	GET POST PATCH DELETE
`/api/tours`	Touren / Umläufe	GET POST PATCH DELETE
`/api/vehicles`	Fahrzeuge	GET POST PATCH DELETE
`/api/route_activities`	Streckenfahrten (Dokumentationen)	GET POST PATCH DELETE
`/api/vehicle_activities`	Fahrzeugfahrten	GET POST PATCH DELETE
`/api/me`	Eigenes Nutzerprofil	GET

Beispiele

Alle Strecken abrufen

GET /api/routes
Authorization: Bearer <token>
Accept: application/ld+json

Antwort:

{
  "@context": "/api/contexts/Route",
  "@id": "/api/routes",
  "@type": "Collection",
  "totalItems": 2,
  "member": [
    {
      "@id": "/api/routes/550e8400-e29b-41d4-a716-446655440000",
      "@type": "Route",
      "uuid": "550e8400-e29b-41d4-a716-446655440000",
      "name": "KBS 400 Hannover - Hamburg",
      "startPoint": "Hannover Hbf",
      "endPoint": "Hamburg Hbf"
    }
  ]
}

Neue Strecke anlegen

POST /api/routes
Authorization: Bearer <token>
Content-Type: application/ld+json

{
  "name": "KBS 400 Hannover - Hamburg",
  "startPoint": "Hannover Hbf",
  "endPoint": "Hamburg Hbf",
  "companyRoute": "RE3"
}

Strecke bearbeiten

PATCH /api/routes/550e8400-e29b-41d4-a716-446655440000
Authorization: Bearer <token>
Content-Type: application/merge-patch+json

{
  "name": "KBS 400 Hannover - Hamburg (aktualisiert)"
}

Strecke löschen

DELETE /api/routes/550e8400-e29b-41d4-a716-446655440000
Authorization: Bearer <token>

Eigenes Profil abrufen

GET /api/me
Authorization: Bearer <token>

Schnellstart mit cURL

# 1. Token holen
TOKEN=$(curl -s -X POST https://streckenkunde.digital/api/login \
  -H "Content-Type: application/json" \
  -d '{"email":"deine@email.de","password":"dein-passwort"}' \
  | grep -o '"token":"[^"]*"' | cut -d'"' -f4)

# 2. Strecken abrufen
curl -s https://streckenkunde.digital/api/routes \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/ld+json"

Fehlercodes

Code	Bedeutung
`401`	Nicht authentifiziert - Token fehlt oder ist abgelaufen
`403`	Keine Berechtigung - Zugriff auf fremde Ressource
`404`	Ressource nicht gefunden
`422`	Validierungsfehler - ungültige Daten
`429`	Zu viele Anfragen - Rate-Limit erreicht

Wichtige Hinweise

Alle Ressourcen werden über UUIDs identifiziert, nicht über numerische IDs.
Beim Erstellen (POST) wird der Eigentümer automatisch gesetzt - das Feld owner wird ignoriert.
Beziehungen (z. B. Touren einer Strecke) werden als IRIs (z. B. /api/tours/uuid) serialisiert, nicht als verschachtelte Objekte.
Zum Bearbeiten wird PATCH mit Content-Type: application/merge-patch+json verwendet.
Du kannst nur auf deine eigenen Daten zugreifen. Fremde Ressourcen liefern 403.

Fair Use

Die API steht allen registrierten Nutzern zur Verfügung. Wir bitten um einen verantwortungsvollen Umgang:

Rate-Limiting: Bitte sende nicht mehr als 60 Anfragen pro Minute. Automatisierte Massenabfragen sind nicht gestattet.
Nur eigene Daten: Die API dient ausschließlich zum Zugriff auf deine eigenen Streckenkunde-Daten. Versuche, auf fremde Daten zuzugreifen, werden blockiert und protokolliert.
Kein Scraping: Das systematische Auslesen oder Kopieren von Daten zum Aufbau eigener Datenbanken oder Dienste ist untersagt.
Keine Weitergabe von Tokens: Dein JWT-Token ist an deinen Account gebunden. Gib es nicht an Dritte weiter.
Persönlicher Gebrauch: Die API ist für den persönlichen Gebrauch gedacht - z. B. eigene Auswertungen, Integrationen in persönliche Tools oder Automatisierungen deiner Dokumentation.
Keine Garantie: Die API wird ohne Verfügbarkeitsgarantie bereitgestellt. Endpunkte, Formate und Limits können sich jederzeit ändern.

Bei Fragen oder speziellen Anforderungen wende dich an kontakt@streckenkunde.digital.

Interaktive API-Dokumentation öffnen