251 lines
9.8 KiB
Text
251 lines
9.8 KiB
Text
% my $api_root = $self->url_for('/api/v1')->to_abs->scheme('https');
|
||
% my $token = stash('api_token') // {};
|
||
% my $uid = stash('uid') // q{};
|
||
|
||
<h1>API</h1>
|
||
|
||
<div class="row">
|
||
<div class="col s12">
|
||
Die folgenden API-Endpunkte werden aktuell unterstützt.
|
||
</div>
|
||
</div>
|
||
|
||
<h2>Status</h2>
|
||
<div class="row">
|
||
<div class="col s12">
|
||
<p style="font-family: Monospace;">
|
||
% if ($token->{status}) {
|
||
curl <%= $api_root %>/status/<%= $uid %>-<%= $token->{status} // 'TOKEN' %>
|
||
% }
|
||
% else {
|
||
curl <%= $api_root %>/status/TOKEN
|
||
% }
|
||
</p>
|
||
<p>
|
||
Beispiel / Layout:
|
||
</p>
|
||
<p style="font-family: Monospace;">
|
||
{<br/>
|
||
"deprecated" : true / false, (falls true: Diese API-Version wird irgendwann abgeschaltet, bitte auf eine neue umsteigen)<br/>
|
||
"actionTime" : 1234567, (UNIX-Timestamp des letzten Checkin/Checkout)<br/>
|
||
"checkedIn" : true / false,<br/>
|
||
"comment": "Kommentar",<br/>
|
||
"backend": {<br/>
|
||
"id": 1,<br/>
|
||
"name": "DB",<br/>
|
||
"type": "HAFAS",<br/>
|
||
},<br/>
|
||
"fromStation" : { (letzter Checkin)<br/>
|
||
"name" : "Essen Hbf",<br/>
|
||
"ds100" : "EE", (ggf. null)<br/>
|
||
"uic" : 8000098,<br/>
|
||
"latitude" : 51.451355,<br/>
|
||
"longitude" : 7.014793,<br/>
|
||
"platform" : "12", (ggf. null)<br/>
|
||
"scheduledTime": 1556083680,<br/>
|
||
"realTime": 1556083680<br/>
|
||
},<br/>
|
||
"toStation" : { (zugehöriger Checkout. Wenn noch nicht eingetragen, sind alle Felder null)<br/>
|
||
"name" : "Essen Stadtwald",<br/>
|
||
"ds100" : "EESA", (ggf. null)<br/>
|
||
"uic" : 8001896,<br/>
|
||
"latitude" : 51.422853,<br/>
|
||
"longitude" : 7.023296,<br/>
|
||
"platform" : "2", (ggf. null)<br/>
|
||
"scheduledTime": 1556083980, (ggf. null)<br/>
|
||
"realTime": 1556083980 (ggf. null)<br/>
|
||
},<br/>
|
||
"intermediateStops" : [ (Unterwegshalte zwischen fromStation und toStation) <br/>
|
||
{<br/>
|
||
"name" : "Essen Süd",<br/>
|
||
"scheduledArrival" : 1556083800, (ggf. null)<br/>
|
||
"realArrival" : 1556083800, (ggf. null, nach Ankunft identisch mit scheduledArrival)<br/>
|
||
"scheduledDeparture" : 1556083860, (ggf. null)<br/>
|
||
"realDeparture" : 1556083860 (ggf. null, nach Abfahrt identisch mit scheduledDeparture)<br/>
|
||
},<br/>
|
||
…<br/>
|
||
],<br/>
|
||
"train" : {<br/>
|
||
"type" : "S", (aktueller / letzter Fahrttyp)<br/>
|
||
"line" : "6", (Linie als String, nicht immer numerisch, ggf. null)<br/>
|
||
"no" : "30634", (Fahrtnummer als String, ggf. null oder leer)<br/>
|
||
"id" : "7512500863736016593" (IRIS- oder HAFAS-spezifische Fahrt-ID)<br/>
|
||
"hafasId" : "1|224479|0|80|30082023" (HAFAS-spezifische Fahrt-ID falls bekannt, ggf. null)<br/>
|
||
},<br/>
|
||
"visibility" : {<br/>
|
||
"desc": "private" / "unlisted" / "followers" / "travelynx" / "public",<br/>
|
||
"level": 10 / 30 / 60 / 80 / 100<br/>
|
||
}<br/>
|
||
}
|
||
</p>
|
||
<p>
|
||
Im Fehlerfall: <span style="font-family: Monospace;">{ "error" : "Begründung" }</span>
|
||
</p>
|
||
</div>
|
||
</div>
|
||
|
||
<h2>Travel</h2>
|
||
<div class="row">
|
||
<div class="col s12">
|
||
<p>
|
||
Checkin per API. Sobald eine Zielstation bekannt ist, erfolgt der
|
||
Checkout wie beim Webinterface automatisch zehn Minuten nach Ankunft.
|
||
Bitte beachten: Es wird nicht überprüft, ob die angegebene Zielstation
|
||
in der vorgesehenen Route der Fahrt vorkommt oder nicht.
|
||
</p>
|
||
<p>
|
||
Falls du zum Checkinzeitpunkt bereits in eine andere Fahrt eingecheckt
|
||
bist, wirst du zunächst am gewählten Startbahnhof aus diesem ausgecheckt.
|
||
Der Checkout erfolgt unabhängig davon, ob die vorherige Fahrt an dieser
|
||
Station verkehrt oder nicht. Falls nach einem Checkin ohne Zielwahl
|
||
innerhalb von 48 Stunden kein Zielbahnhof nachgetragen wird, wird der
|
||
Checkin automatisch rückgängig gemacht.
|
||
</p>
|
||
<p>
|
||
Das Verhalten des Checkout-Endpunkts hängt vom Zeitpunkt ab. Wenn die
|
||
Fahrt den angegebenen Zielbahnhof bereits erreicht hat, wird dort
|
||
ausgecheckt. Andernfalls wird das Reiseziel aktualisiert und etwa zehn
|
||
Minuten nach Ankunft automatisch ausgecheckt.
|
||
</p>
|
||
<p style="font-family: Monospace;">
|
||
curl -X POST -H "Content-Type: application/json" -d '{"token":"<%= $uid %>-<%= $token->{travel} // 'TOKEN' %>"}' <%= $api_root %>/travel
|
||
</p>
|
||
<p>Payload zum Einchecken per IRIS-Backend (Schienenverkehr DE/DB), optional mit Zielwahl:</p>
|
||
<p style="font-family: Monospace;">
|
||
{<br/>
|
||
"token" : "<%= $uid %>-<%= $token->{travel} // 'TOKEN' %>",<br/>
|
||
"action" : "checkin",<br/>
|
||
"train" : {<br/>
|
||
"type" : "ICE",<br/>
|
||
"no" : "1234",<br/>
|
||
}<br/>
|
||
"fromStation" : "Essen Hbf", (DS100 oder EVA-Nummer sind ebenfalls möglich)<br/>
|
||
"toStation" : "Berlin Hbf", (optional, DS100 oder EVA-Nummer sind ebenfalls möglich)<br/>
|
||
"comment" : "Beliebiger Text" (optional, überschreibt vorherigen Kommentar)<br/>
|
||
}
|
||
</p>
|
||
<p>Payload zum Einchecken per HAFAS-Backend (Nahverkehr und außerhalb DE/DB), optional mit Zielwahl. fromStation und toStation müssen mit den Unterwegshalten übereinstimmen, z.B. "Hauptbahnhof (U Gleis 2+4), Essen (Ruhr)" statt "Essen Hbf".</p>
|
||
<p style="font-family: Monospace;">
|
||
{<br/>
|
||
"token" : "<%= $uid %>-<%= $token->{travel} // 'TOKEN' %>",<br/>
|
||
"action" : "checkin",<br/>
|
||
"hafas" : "DB", (HAFAS-Instanz – Default: Deutsche Bahn)<br/>
|
||
"train" : {<br/>
|
||
"journeyID" : "1|1426396|4|80|19082023",<br/>
|
||
}<br/>
|
||
"fromStation" : 651806, (Name oder EVA-Nummer)<br/>
|
||
"toStation" : 654645, (optional, Name oder EVA-Nummer)<br/>
|
||
"comment" : "Beliebiger Text" (optional, überschreibt vorherigen Kommentar)<br/>
|
||
}
|
||
</p>
|
||
<p>Payload zur Wahl eines neuen Ziels, wenn bereits eingecheckt:</p>
|
||
<p style="font-family: Monospace;">
|
||
{<br/>
|
||
"token" : "<%= $uid %>-<%= $token->{travel} // 'TOKEN' %>",<br/>
|
||
"action" : "checkout",<br/>
|
||
"force" : true/false, (wenn true: Checkout jetzt durchführen und auftretende Fehler ignorieren. Kann zu Logeinträgen ohne Ankunftszeit führen.)<br/>
|
||
"toStation" : "Berlin Hbf", (DS100 oder EVA-Nummer sind ebenfalls möglich)<br/>
|
||
"comment" : "Beliebiger Text" (optional, überschreibt vorherigen Kommentar)<br/>
|
||
}
|
||
</p>
|
||
<p>Payload zum Rückgängigmachen eines Checkins (nur während der Fahrt möglich):</p>
|
||
<p style="font-family: Monospace;">
|
||
{<br/>
|
||
"token" : "<%= $uid %>-<%= $token->{travel} // 'TOKEN' %>",<br/>
|
||
"action" : "undo"<br/>
|
||
}
|
||
</p>
|
||
<p>
|
||
Antwort bei Erfolg:
|
||
</p>
|
||
<p style="font-family: Monospace;">
|
||
{<br/>
|
||
"success" : true,<br/>
|
||
"deprecated" : true / false, (falls true: Diese API-Version wird irgendwann abgeschaltet, bitte auf eine neue umsteigen)<br/>
|
||
"status" : { aktueller Nutzerstatus gemäß Status-API }<br/>
|
||
}
|
||
</p>
|
||
<p>
|
||
Antwort bei Fehler:
|
||
</p>
|
||
<p style="font-family: Monospace;">
|
||
{<br/>
|
||
"success" : false,<br/>
|
||
"deprecated" : true / false, (falls true: Diese API-Version wird irgendwann abgeschaltet, bitte auf eine neue umsteigen)<br/>
|
||
"error" : "Begründung",<br/>
|
||
"status" : { aktueller Nutzerstatus gemäß Status-API } (nur bei gültigem Token)<br/>
|
||
}
|
||
</p>
|
||
</div>
|
||
</div>
|
||
|
||
<h2>Import</h2>
|
||
<div class="row">
|
||
<div class="col s12">
|
||
<p>
|
||
Manueller Import vergangener Fahrten (eine Fahrt pro API-Aufruf).
|
||
</p>
|
||
<p>
|
||
Bitte beachten: fromStation, toStation und intermediateStops werden
|
||
mit Fuzzy Matching eingelesen. Falls ein unbekannter Stationsname
|
||
einer anderen, bekannten Station hinreichend ähnelt, kann dieser
|
||
dadurch ersetzt werden. Bei Unsicherheiten empfiehlt sich ein
|
||
<em>dryRun</em> und ein Vergleich der zurückgegebenen Stationsnamen
|
||
mit den eingegebenen. Komplett unbekannte Stationsnamen führen
|
||
standardmäßig zu einem Fehler (siehe <em>lax</em>)
|
||
</p>
|
||
<p style="font-family: Monospace;">
|
||
curl -X POST -H "Content-Type: application/json" -d '{"token":"<%= $uid %>-<%= $token->{import} // 'TOKEN' %>"}' <%= $api_root %>/import
|
||
</p>
|
||
<p>Payload (alle nicht als optional markierten Felder sind Pflicht):</p>
|
||
<p style="font-family: Monospace;">
|
||
{<br/>
|
||
"token" : "<%= $uid %>-<%= $token->{import} // 'TOKEN' %>",<br/>
|
||
"dryRun" : true/false, (optional: wenn true, wird die Eingabe validiert, aber keine Fahrt angelegt)<br/>
|
||
"lax" : true/false, (optional: wenn true, werden unbekannte Unterwegshalte akzeptiert)<br/>
|
||
"cancelled" : true/false, (Ausfall?)<br/>
|
||
"train" : {<br/>
|
||
"type" : "S", (Typ, z.B. ICE, RE, S, U)<br/>
|
||
"line" : "6", (Linie als String, bei Zügen ohne Linie wie IC/ICE u.ä. null)<br/>
|
||
"no" : "30634", (Nummer als String, ggf. null oder leer)<br/>
|
||
},<br/>
|
||
"fromStation" : { (Start / Checkin)<br/>
|
||
"name" : "Essen Hbf", (Name oder DS100)<br/>
|
||
"scheduledTime": 1556083680, (UNIX-Timestamp)<br/>
|
||
"realTime": 1556083680, (UNIX-Timestamp, optional, default == scheduledTime)<br/>
|
||
},<br/>
|
||
"toStation" : { (Ziel / Checkout)<br/>
|
||
"name" : "Essen Stadtwald", (Name oder DS100)<br/>
|
||
"scheduledTime": 1556083980, (UNIX-Timestamp)<br/>
|
||
"realTime": 1556083980, (UNIX-Timestamp, optional, default == scheduledTime)<br/>
|
||
},<br/>
|
||
"intermediateStops" : [ (optionale Liste mit Unterwegshalten als Name oder DS100, darf keine Stationen vor Checkin oder nach Checkout beinhalten)<br/>
|
||
"Essen Süd",<br/>
|
||
],<br/>
|
||
"comment" : "Beliebiger Text" (optionaler Freitext-Kommentar)<br/>
|
||
}
|
||
</p>
|
||
<p>
|
||
Antwort bei Erfolg (der Inhalt von "result" ist von dryRun unabhängig):
|
||
</p>
|
||
<p style="font-family: Monospace;">
|
||
{<br/>
|
||
"success" : true,<br/>
|
||
"deprecated" : true / false, (falls true: Diese API-Version wird irgendwann abgeschaltet, bitte auf eine neue umsteigen)<br/>
|
||
"id" : 1234, (ID der eingetragenen Fahrt)<br/>
|
||
"result" : { ... } (Eingetragene Daten. Das Datenformat kann sich
|
||
ohne Berücksichtigung der API-Version ändern)<br/>
|
||
}
|
||
</p>
|
||
<p>
|
||
Antwort bei Fehler:
|
||
</p>
|
||
<p style="font-family: Monospace;">
|
||
{<br/>
|
||
"success" : false,<br/>
|
||
"deprecated" : true / false, (falls true: Diese API-Version wird irgendwann abgeschaltet, bitte auf eine neue umsteigen)<br/>
|
||
"error" : "Begründung"<br/>
|
||
}
|
||
</p>
|
||
</div>
|
||
</div>
|