API Dokumentation

Diese Dokumentation beschreibt den Zugriff auf unsere HTTP-API sowie die Nutzung von Webhooks. Bitte lesen Sie die folgenden Abschnitte sorgfältig durch, um die korrekte Integration in Ihre Systeme sicherzustellen.

1. Zugriff auf die API

Authentifizierung

• Der API-Zugriff ist auf technische Benutzer beschränkt.
• Bei der erstmaligen Erstellung eines technischen Benutzers wird ein API-Schlüssel generiert und angezeigt. Dieser Schlüssel wird nicht erneut angezeigt und muss sicher gespeichert werden.
• Die Authentifizierung erfolgt über den API-Schlüssel als Bearer Token.

IP Beschränkung

• Aktuell ist der Zugriff auf STEIN auf IP-Adressen aus Deutschland beschränkt. Dies trifft auch auf die API zu.
• IP-Adressen aus dem Ausland erhalten generell den HTTP Status 404 und den Text "The requested URL was not found on this webserver." als Antwort.

Beispielhafter API-Aufruf

curl -X GET "https://stein.app/api/api/ext/assets/?buId=21" \
 -H "Authorization: Bearer {API_KEY}" \
 -H "Accept: application/json"

Häufige HTTP-Fehlercodes

• 200 OK - Anfrage war erfolgreich
• 400 Bad Request - Ungültiges Anfrageformat
• 401 Unauthorized - Fehlende oder falsche Authentifizierung
• 403 Forbidden - Zugriff verweigert
• 404 Not Found - Angeforderte Ressource nicht gefunden
• 429 Too Many Requests - Rate-Limit überschritten
• 500 Internal Server Error - Serverfehler aufgetreten

Rate-Limit

• Die API erlaubt maximal 20 Anfragen pro Minute pro IP.
• Wird dieses Limit überschritten, wird die IP für eine Stunde gesperrt.
• Regelmäßiges automatisiertes Abfragen (z. B. jede Minute) wird nicht empfohlen; stattdessen sollten Webhooks verwendet werden.
• Übermäßige wiederholte Anfragen können zur automatischen Sperrung der IP führen.

Verfügbare APIs

Aktuell sind folgende APIs verfügbar. Diese basieren zurzeit auf den Anforderungen der Web-Oberfläche und können sich in Zukunft ändern.

Detaillierte Dokumentation: https://stein.app/api/api/doc/ui. Swagger File: https://stein.app/api/api/doc/api-doc.yaml.

Aus technischen Gründen sind in der Swagger File noch Schemas enthalten, welche für die API nicht relevant sind (z. B. "Role" oder "UserInfo").

Ortsverbände

• Lesen eines Ortsverbandes

Fahrzeuge, Anhänger, ...

• Lesen aller Fahrzeuge eines Ortsverbandes
• Lesen eines Fahrzeuges
• Ändern eines bestehenden Fahrzeugs

2. Webhook-Integration

Einrichtung

• Eine Webhook-URL kann pro Standort ("Ortsverband") über die Benutzeroberfläche konfiguriert werden.
• Jeder Ortsverband erhält einen eindeutigen Webhook-Secret, der in den OV-Einstellungen angezeigt wird.
• Die Authentifizierung erfolgt über den HTTP-Header X-Secret. Das Script muss in jedem Fall diesen Header prüfen, um die Echtheit der Anfrage sicherzustellen.

Webhook-Payload

Webhooks enthalten nur minimale Informationen und geben an, welche Entität betroffen ist. Die vollständigen Details können über das "URL"-Feld in der API abgerufen werden.

{
   "meta": {
      "eventId": "STEIN-1742652612538",
      "environmentName": "uebung",
      "timestamp": "2025-03-22T15:10:12+01:00"
   },
   "items": [
      {
         "type": "asset",
         "action": "update",
         "id": 206,
         "url": "https://stein.app/api/api/ext/assets/206"
      },
      {
         "type": "bu",
         "action": "update",
         "id": 10,
         "url": "https://stein.app/api/api/ext/bu/10"
      }
   ]
}

Metadaten-Felder

• eventId: Eindeutige Kennung des Ereignisses
• environmentName: Umgebung ("uebung", "test" oder "prod")
• timestamp: Zeitpunkt der Änderung im ISO-Format

Verarbeitungsrichtlinien

• Webhook-Anfragen sollten innerhalb von 2 Sekunden verarbeitet werden.
• Lang andauernde Operationen sollten asynchron ausgeführt werden.
• Zur Bestätigung der Verarbeitung muss ein erfolgreicher HTTP-Statuscode zurückgegeben werden.

Wiederholungsmechanismus

• Im Fehlerfall wird die Webhook-Zustellung bis zu 5 Mal wiederholt.
• Die Wartezeit zwischen den Wiederholungen erhöht sich exponentiell.

Fehlervermeidung

• Falls das Webhook-Verarbeitungsskript offline genommen wird, sollte die Webhook-URL entfernt werden, um unnötige Fehlanfragen zu vermeiden.

Webhook-Prinzipien

• Webhooks folgen dem "at least once"-Zustellungsprinzip.
• Mehrere Webhook-Aufrufe für eine einzelne Änderung sind möglich.
• Ereignisse können anhand der eventId dedupliziert werden.

Unterstützte Objekte und Aktionen

• Assets (z. B. Fahrzeuge, Anhänger)
• Bus (Ortsverbände)

Mögliche Aktionen:

• create - Neues Objekt erstellt
• update - Bestehendes Objekt geändert
• delete - Objekt gelöscht