diff options
Diffstat (limited to 'templates/api_documentation.html.ep')
| -rw-r--r-- | templates/api_documentation.html.ep | 136 |
1 files changed, 89 insertions, 47 deletions
diff --git a/templates/api_documentation.html.ep b/templates/api_documentation.html.ep index e5d026f..6db9536 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,55 @@ <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",<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/> + "realTime": 1556083680<br/> },<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/> + "platform" : "2", (ggf. null)<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> @@ -65,35 +84,35 @@ </div> </div> -% if (app->mode eq 'development') { - <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 des Zugs vorkommt oder nicht. + Checkout wie beim Webinterface automatisch spätestens eine halbe + Stunde 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 einen anderen Zug eingecheckt - bist, wirst du zunächst am gewählten Startbahnhof aus diesem ausgecheckt. - Der Checkout erfolgt unabhängig davon, ob der vorherige Zug 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. + 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 der - Zug den angegebenen Zielbahnhof bereits erreicht hat, wird dort - ausgecheckt. Andernfalls wird das Reiseziel aktualisiert und etwa zehn - Minuten nach Ankunft automatisch ausgecheckt. + 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 + spätestens eine halbe Stunde 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, optional mit Zielwahl:</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/> @@ -107,6 +126,21 @@ "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/> + "dbris" : "bahn.de", (DBRIS-Instanz – Default: bahn.de)<br/> + "hafas" : null, (HAFAS-Instanz, falls verwendet, sonste null)<br/> + "train" : {<br/> + "journeyID" : "2|#VN#1#ST#1742845592#PI#0#ZI#315136#TA#0#DA#270325#1S#8000080#1T#1841#LS#8006486#LT#2024#PU#80#RT#1#CA#RE#ZE#10773#ZB#RE10773#PC#3#FR#8000080#FT#1841#TO#8006486#TT#2024#",<br/> + }<br/> + "fromStation" : 8000080, (Name oder EVA-Nummer – bei bahn.de nur EVA-Nummer)<br/> + "toStation" : 8006486, (optional, Name oder EVA-Nummer – bei bahn.de nur 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/> @@ -152,7 +186,16 @@ <div class="row"> <div class="col s12"> <p> - Manueller Import vergangener Zugfahrten (eine Fahrt pro API-Aufruf). + 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 @@ -161,28 +204,26 @@ <p style="font-family: Monospace;"> {<br/> "token" : "<%= $uid %>-<%= $token->{import} // 'TOKEN' %>",<br/> - "dryRun" : true/false, (optional: wenn true, wird die Eingabe validiert, aber keine Zugfahrt angelegt)<br/> - "lax" : true/Fals, (optional: wenn true, werden unbekannte Unterwegshalte akzeptiert)<br/> - "cancelled" : true/false, (Zugausfall?)<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", (Zugtyp, z.B. ICE, RE, S)<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", (Zugnummer als String)<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/> + "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/> - "route" : [ (optionale Liste mit Unterwegshalten als Name oder DS100, darf keine Stationen vor Checkin oder nach Checkout beinhalten)<br/> - "Essen Hbf",<br/> + "intermediateStops" : [ (optionale Liste mit Unterwegshalten als Name oder DS100, darf keine Stationen vor Checkin oder nach Checkout beinhalten)<br/> "Essen Süd",<br/> - "Essen Stadtwald"<br/> ],<br/> "comment" : "Beliebiger Text" (optionaler Freitext-Kommentar)<br/> } @@ -193,8 +234,10 @@ <p style="font-family: Monospace;"> {<br/> "success" : true,<br/> - "id" : 1234, (ID der eingetragenen Zugfahrt)<br/> - "result" : { ... } (Eingetragene Daten, Datenformat nicht näher spezifiziert und beliebig variabel)<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> @@ -203,10 +246,9 @@ <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> - -% } |