% my $api_root = $self->url_for('/api/v1')->to_abs->scheme('https'); % my $token = {}; % my $uid; % if (is_user_authenticated()) { % $uid = current_user()->{id}; % $token = get_api_token(); % }

API

Die folgenden API-Endpunkte werden aktuell unterstützt.

Status

% if ($token->{status}) { curl <%= $api_root %>/status/<%= $uid %>-<%= $token->{status} // 'TOKEN' %> % } % else { curl <%= $api_root %>/status/TOKEN % }

Beispiel / Layout:

{
"deprecated" : true / false, (falls true: Diese API-Version wird irgendwann abgeschaltet, bitte auf eine neue umsteigen)
"checkedIn" : true / false,
"fromStation" : { (letzter Checkin)
"name" : "Essen Hbf",
"ds100" : "EE",
"uic" : 8000098,
"latitude" : 51.451355,
"longitude" : 7.014793,
"scheduledTime": 1556083680,
"realTime": 1556083680,
},
"toStation" : { (zugehöriger Checkout. Wenn noch nicht eingetragen, sind alle Felder null)
"name" : "Essen Stadtwald",
"ds100" : "EESA",
"uic" : 8001896,
"latitude" : 51.422853,
"longitude" : 7.023296,
"scheduledTime": 1556083980, (ggf. null)
"realTime": 1556083980, (ggf. null)
},
"train" : {
"type" : "S", (aktueller / letzter Zugtyp)
"line" : "6", (Linie als String, nicht immer numerisch, ggf. null)
"no" : "30634", (Zugnummer als String)
"id" : "7512500863736016593", (IRIS-spezifische Zug-ID)
},
"actionTime" : 1234567, (UNIX-Timestamp des letzten Checkin/Checkout)
}

Im Fehlerfall: { "error" : "Begründung" }

Travel

Checkin per API. Sobald eine Zielstation bekannt ist, erfolgt der Checkout wie beim Webinterface automatisch zehn Minuten nach Ankunft.

curl -X POST -H "Content-Type: application/json" -d '{"token":"<%= $uid %>-<%= $token->{travel} // 'TOKEN' %>"}' <%= $api_root %>/travel

Payload zum Einchecken, optional mit Zielwahl:

{
"token" : "<%= $uid %>-<%= $token->{import} // 'TOKEN' %>",
"action" : "checkin",
"train" : {
"type" : "ICE",
"no" : "1234",
}
"fromStation" : "Essen Hbf", (DS100 oder EVA-Nummer sind ebenfalls möglich)
"toStation" : "Berlin Hbf", (optional, DS100 oder EVA-Nummer sind ebenfalls möglich)
"comment" : "Beliebiger Text" (optional)
}

Payload zur Wahl eines neuen Ziels, wenn bereits eingecheckt:

{
"token" : "<%= $uid %>-<%= $token->{import} // 'TOKEN' %>",
"action" : "checkout",
"force" : True/False, (wenn True: Checkout jetzt durchführen und auftretende Fehler ignorieren. Kann zu Logeinträgen ohne Ankunftsdaten führen.)
"toStation" : "Berlin Hbf", (DS100 oder EVA-Nummer sind ebenfalls möglich)
"comment" : "Beliebiger Text" (optional)
}

Payload zum Rückgängigmachen eines Checkins (nur während der Fahrt möglich):

{
"token" : "<%= $uid %>-<%= $token->{import} // 'TOKEN' %>",
"action" : "undo"
}

Antwort bei Erfolg:

{
"success" : True,
"status" : { aktueller Nutzerstatus gemäß Status-API }
}

Antwort bei Fehler:

{
"success" : False,
"error" : "Begründung",
"status" : { aktueller Nutzerstatus gemäß Status-API }
}

Import

Manueller Import vergangener Zugfahrten (eine Fahrt pro API-Aufruf).

curl -X POST -H "Content-Type: application/json" -d '{"token":"<%= $uid %>-<%= $token->{status} // 'TOKEN' %>"}' <%= $api_root %>/import

Payload (alle nicht als optional markierten Felder sind Pflicht):

{
"token" : "<%= $uid %>-<%= $token->{import} // 'TOKEN' %>",
"dryRun" : True/False, (optional: wenn True, wird die Eingabe validiert, aber keine Zugfahrt angelegt)
"cancelled" : True/False, (Zugausfall?)
"train" : {
"type" : "S", (Zugtyp, z.B. ICE, RE, S)
"line" : "6", (Linie als String, bei Zügen ohne Linie wie IC/ICE u.ä. null)
"no" : "30634", (Zugnummer als String)
},
"fromStation" : { (Start / Checkin)
"name" : "Essen Hbf", (Name oder DS100)
"scheduledTime": 1556083680, (UNIX-Timestamp)
"realTime": 1556083680, (UNIX-Timestamp, optional, default == scheduledTime)
},
"toStation" : { (Ziel / Checkout)
"name" : "Essen Stadtwald", (Name oder DS100)
"scheduledTime": 1556083980, (UNIX-Timestamp)
"realTime": 1556083980, (UNIX-Timestamp, optional, default == scheduledTime)
},
"route" : [ (optionale Liste mit Unterwegshalten als Name oder DS100, darf keine Stationen vor Checkin oder nach Checkout beinhalten)
"Essen Hbf",
"Essen Süd",
"Essen Stadtwald"
],
"comment" : "Beliebiger Text" (optionaler Freitext-Kommentar)
}

Antwort bei Erfolg (der Inhalt von "result" ist von dryRun unabhängig):

{
"success" : True,
"id" : 1234, (ID der eingetragenen Zugfahrt)
"result" : { ... } (Eingetragene Daten, Inhalt ist variabel)
}

Antwort bei Fehler:

{
"success" : False,
"error" : "Begründung"
}