diff options
Diffstat (limited to 'templates/api_documentation.html.ep')
| -rw-r--r-- | templates/api_documentation.html.ep | 202 |
1 files changed, 180 insertions, 22 deletions
diff --git a/templates/api_documentation.html.ep b/templates/api_documentation.html.ep index dd59be6..9c9ee1f 100644 --- a/templates/api_documentation.html.ep +++ b/templates/api_documentation.html.ep @@ -1,10 +1,6 @@ % 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(); -% } +% my $token = stash('api_token') // {}; +% my $uid = stash('uid') // q{}; <h1>API</h1> @@ -31,32 +27,48 @@ <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/> "fromStation" : { (letzter Checkin)<br/> "name" : "Essen Hbf",<br/> - "ds100" : "EE",<br/> + "ds100" : "EE", (ggf. null)<br/> "uic" : 8000098,<br/> "latitude" : 51.451355,<br/> "longitude" : 7.014793,<br/> "scheduledTime": 1556083680,<br/> - "realTime": 1556083680,<br/> + "realTime": 1556083680<br/> },<br/> - "fromStation" : { (zugehöriger Checkout. Wenn noch nicht eingetragen, sind alle Felder null)<br/> + "toStation" : { (zugehöriger Checkout. Wenn noch nicht eingetragen, sind alle Felder null)<br/> "name" : "Essen Stadtwald",<br/> - "ds100" : "EESA",<br/> + "ds100" : "EESA", (ggf. null)<br/> "uic" : 8001896,<br/> "latitude" : 51.422853,<br/> "longitude" : 7.023296,<br/> "scheduledTime": 1556083980, (ggf. null)<br/> - "realTime": 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 Zugtyp)<br/> - "line" : "6", (Linie als String, nicht immer numerisch, ggf. null)<br/> - "no" : "30634", (Zugnummer als String)<br/> - "id" : "7512500863736016593", (IRIS-spezifische Zug-ID)<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/> - "actionTime" : 1234567, (UNIX-Timestamp des letzten Checkin/Checkout)<br/> + "visibility" : {<br/> + "desc": "private" / "unlisted" / "followers" / "travelynx" / "public",<br/> + "level": 10 / 30 / 60 / 80 / 100<br/> + }<br/> } </p> <p> @@ -64,22 +76,168 @@ </p> </div> </div> -<!-- -<h3>History</h3> + +<h2>Travel</h2> <div class="row"> <div class="col s12"> <p> - Coming soon. + 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/> + "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> -<h3>Travel</h3> +<h2>Import</h2> <div class="row"> <div class="col s12"> <p> - Ein- und Auschecken per API. Coming soon. + 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> ---> |