travelynx/templates/api_documentation.html.ep

% 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();
% }

<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/>
			"checkedIn" : true / false,<br/>
			"fromStation" : { (letzter Checkin)<br/>
				"name" : "Essen Hbf",<br/>
				"ds100" : "EE",<br/>
				"uic" : 8000098,<br/>
				"latitude" : 51.451355,<br/>
				"longitude" : 7.014793,<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",<br/>
				"uic" : 8001896,<br/>
				"latitude" : 51.422853,<br/>
				"longitude" : 7.023296,<br/>
				"scheduledTime": 1556083980, (ggf. null)<br/>
				"realTime": 1556083980, (ggf. null)<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/>
			},<br/>
			"actionTime" : 1234567, (UNIX-Timestamp des letzten Checkin/Checkout)<br/>
		}
		</p>
		<p>
			Im Fehlerfall: <span style="font-family: Monospace;">{ "error" : "Begründung" }</span>
		</p>
	</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.
		</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 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)<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 Ankunftsdaten führen.)<br/>
			"toStation" : "Berlin Hbf", (DS100 oder EVA-Nummer sind ebenfalls möglich)<br/>
			"comment" : "Beliebiger Text" (optional)<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/>
			"status" : { aktueller Nutzerstatus gemäß Status-API }<br/>
		}
		</p>
		<p>
			Antwort bei Fehler:
		</p>
		<p style="font-family: Monospace;">
		{<br/>
			"success" : False,<br/>
			"error" : "Begründung",<br/>
			"status" : { aktueller Nutzerstatus gemäß Status-API }<br/>
		}
		</p>
	</div>
</div>

<h2>Import</h2>
<div class="row">
	<div class="col s12">
		<p>
			Manueller Import vergangener Zugfahrten (eine Fahrt pro API-Aufruf).
		</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 Zugfahrt angelegt)<br/>
			"lax" : True/Fals, (optional: wenn True, werden unbekannte Unterwegshalte akzeptiert)<br/>
			"cancelled" : True/False, (Zugausfall?)<br/>
			"train" : {<br/>
			"type" : "S", (Zugtyp, z.B. ICE, RE, S)<br/>
			"line" : "6", (Linie als String, bei Zügen ohne Linie wie IC/ICE u.ä. null)<br/>
			"no" : "30634", (Zugnummer als String)<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/>
			"route" : [ (optionale Liste mit Unterwegshalten als Name oder DS100, darf keine Stationen vor Checkin oder nach Checkout beinhalten)<br/>
				"Essen Hbf",<br/>
				"Essen Süd",<br/>
				"Essen Stadtwald"<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/>
			"id" : 1234, (ID der eingetragenen Zugfahrt)<br/>
			"result" : { ... } (Eingetragene Daten, Datenformat nicht näher spezifiziert und beliebig variabel)<br/>
		}
		</p>
		<p>
			Antwort bei Fehler:
		</p>
		<p style="font-family: Monospace;">
		{<br/>
			"success" : False,<br/>
			"error" : "Begründung"<br/>
		}
		</p>
	</div>
</div>

% }