Travel API: Add "deprecated" field

2 files changed, 59 insertions, 38 deletions

diff --git a/lib/Travelynx/Controller/Api.pm b/lib/Travelynx/Controller/Api.pm
index f5ea3e4..f0fa5db 100755
--- a/lib/Travelynx/Controller/Api.pm
+++ b/lib/Travelynx/Controller/Api.pm
@@ -174,8 +174,9 @@ sub travel_v1 {
 	if ( not $payload or ref($payload) ne 'HASH' ) {
 		$self->render(
 			json => {
-				success => \0,
-				error   => 'Malformed JSON',
+				success    => \0,
+				deprecated => \0,
+				error      => 'Malformed JSON',
 			},
 		);
 		return;
@@ -184,7 +185,8 @@ sub travel_v1 {
 	if ( $self->app->mode ne 'development' ) {
 		$self->render(
 			json => {
-				success => \0,
+				success    => \0,
+				deprecated => \0,
 				error =>
 'This feature is incomplete and only available in development mode',
 			},
@@ -197,8 +199,9 @@ sub travel_v1 {
 	if ( $api_token !~ qr{ ^ (?<id> \d+ ) - (?<token> .* ) $ }x ) {
 		$self->render(
 			json => {
-				success => \0,
-				error   => 'Malformed token',
+				success    => \0,
+				deprecated => \0,
+				error      => 'Malformed token',
 			},
 		);
 		return;
@@ -209,8 +212,9 @@ sub travel_v1 {
 	if ( $uid > 2147483647 ) {
 		$self->render(
 			json => {
-				success => \0,
-				error   => 'Malformed token',
+				success    => \0,
+				deprecated => \0,
+				error      => 'Malformed token',
 			},
 		);
 		return;
@@ -220,8 +224,9 @@ sub travel_v1 {
 	if ( $api_token ne $token->{'travel'} ) {
 		$self->render(
 			json => {
-				success => \0,
-				error   => 'Invalid token',
+				success    => \0,
+				deprecated => \0,
+				error      => 'Invalid token',
 			},
 		);
 		return;
@@ -232,8 +237,9 @@ sub travel_v1 {
 	{
 		$self->render(
 			json => {
-				success => \0,
-				error   => 'Missing or invalid action',
+				success    => \0,
+				deprecated => \0,
+				error      => 'Missing or invalid action',
 			},
 		);
 		return;
@@ -269,8 +275,9 @@ sub travel_v1 {
 			if ( not defined $train ) {
 				$self->render(
 					json => {
-						success => \0,
-						error   => 'Fehler am Abfahrtsbahnhof: '
+						success    => \0,
+						deprecated => \0,
+						error      => 'Fehler am Abfahrtsbahnhof: '
 						  . $status->{errstr},
 						status => $self->get_user_status_json_v1($uid)
 					}
@@ -292,17 +299,19 @@ sub travel_v1 {
 		if ($error) {
 			$self->render(
 				json => {
-					success => \0,
-					error   => $error,
-					status  => $self->get_user_status_json_v1($uid)
+					success    => \0,
+					deprecated => \0,
+					error      => $error,
+					status     => $self->get_user_status_json_v1($uid)
 				}
 			);
 		}
 		else {
 			$self->render(
 				json => {
-					success => \1,
-					status  => $self->get_user_status_json_v1($uid)
+					success    => \1,
+					deprecated => \0,
+					status     => $self->get_user_status_json_v1($uid)
 				}
 			);
 		}
@@ -320,17 +329,19 @@ sub travel_v1 {
 		if ($error) {
 			$self->render(
 				json => {
-					success => \0,
-					error   => $error,
-					status  => $self->get_user_status_json_v1($uid)
+					success    => \0,
+					deprecated => \0,
+					error      => $error,
+					status     => $self->get_user_status_json_v1($uid)
 				}
 			);
 		}
 		else {
 			$self->render(
 				json => {
-					success => \1,
-					status  => $self->get_user_status_json_v1($uid)
+					success    => \1,
+					deprecated => \0,
+					status     => $self->get_user_status_json_v1($uid)
 				}
 			);
 		}
@@ -340,17 +351,19 @@ sub travel_v1 {
 		if ($error) {
 			$self->render(
 				json => {
-					success => \0,
-					error   => $error,
-					status  => $self->get_user_status_json_v1($uid)
+					success    => \0,
+					deprecated => \0,
+					error      => $error,
+					status     => $self->get_user_status_json_v1($uid)
 				}
 			);
 		}
 		else {
 			$self->render(
 				json => {
-					success => \1,
-					status  => $self->get_user_status_json_v1($uid)
+					success    => \1,
+					deprecated => \0,
+					status     => $self->get_user_status_json_v1($uid)
 				}
 			);
 		}
diff --git a/templates/api_documentation.html.ep b/templates/api_documentation.html.ep
index 2e3e66d..53159a1 100644
--- a/templates/api_documentation.html.ep
+++ b/templates/api_documentation.html.ep
@@ -73,6 +73,12 @@
 		<p>
 			Checkin per API. Sobald eine Zielstation bekannt ist, erfolgt der
 			Checkout wie beim Webinterface automatisch zehn Minuten nach Ankunft.
+			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.
 		</p>
 		<p style="font-family: Monospace;">
 			curl -X POST -H "Content-Type: application/json" -d '{"token":"<%= $uid %>-<%= $token->{travel} // 'TOKEN' %>"}' <%= $api_root %>/travel
@@ -88,7 +94,7 @@
 			}<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/>
+			"comment" : "Beliebiger Text" (optional, überschreibt vorherigen Kommentar)<br/>
 		}
 		</p>
 		<p>Payload zur Wahl eines neuen Ziels, wenn bereits eingecheckt:</p>
@@ -96,9 +102,9 @@
 		{<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/>
+			"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/>
+			"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>
@@ -113,7 +119,8 @@
 		</p>
 		<p style="font-family: Monospace;">
 		{<br/>
-			"success" : True,<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>
@@ -122,7 +129,8 @@
 		</p>
 		<p style="font-family: Monospace;">
 		{<br/>
-			"success" : False,<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 }<br/>
 		}
@@ -143,9 +151,9 @@
 		<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 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/>
@@ -174,7 +182,7 @@
 		</p>
 		<p style="font-family: Monospace;">
 		{<br/>
-			"success" : True,<br/>
+			"success" : true,<br/>
 			"id" : 1234, (ID der eingetragenen Zugfahrt)<br/>
 			"result" : { ... } (Eingetragene Daten, Datenformat nicht näher spezifiziert und beliebig variabel)<br/>
 		}
@@ -184,7 +192,7 @@
 		</p>
 		<p style="font-family: Monospace;">
 		{<br/>
-			"success" : False,<br/>
+			"success" : false,<br/>
 			"error" : "Begründung"<br/>
 		}
 		</p>