From f46fac16208db8424f54f8175bc932bfb8d537df Mon Sep 17 00:00:00 2001
From: Jiri Kalvoda <jirikalvoda@kam.mff.cuni.cz>
Date: Mon, 26 Sep 2022 16:45:00 +0200
Subject: [PATCH] =?UTF-8?q?Strategick=C3=A1:=20Dokumentace=20API=20=C3=BA?=
 =?UTF-8?q?=C4=8Dastn=C3=ADk=C5=AFm?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 server/hra/web/pages.py |   2 +
 server/static/api.md    | 121 ++++++++++++++++++++++++++++++++++++++++
 2 files changed, 123 insertions(+)
 create mode 100644 server/static/api.md

diff --git a/server/hra/web/pages.py b/server/hra/web/pages.py
index 4e46c77..2c422ec 100644
--- a/server/hra/web/pages.py
+++ b/server/hra/web/pages.py
@@ -259,6 +259,8 @@ def web_index():
     with b.p():
         u = app.url_for('static', filename='pravidla.pdf')
         b.a(href=u)("V PDF")
+        u = app.url_for('static', filename='api.md')
+        b.a(href=u)("API (md)")
 
     return b.print_file()
 
diff --git a/server/static/api.md b/server/static/api.md
new file mode 100644
index 0000000..30e3439
--- /dev/null
+++ b/server/static/api.md
@@ -0,0 +1,121 @@
+Obsazování území
+================
+
+API
+---
+
+Odpověď na libovolný dotaz muže být HTTP error ve tvaru:
+```
+{
+	status: "error"
+	description: <str> # Popis chybové události (toto chceme vytisknout!)
+	http-code: <int>
+	http-name: <str> # Jméno chybového kódu
+}
+```
+
+Parametry:
+- token: Identifikuje uživatele, zjistí z hlavní stránky webu
+- game: S jakou hrou (popř. týmem ve hře) se chtějí bavit
+	- Pro naše potřeby:
+		- `main` - Hlavní hra
+		- `test_{0,1,..}` Testovací hra daného uživatele (číslo je jako který tým hrají)
+- round_id: To zjistí z otazu na stav
+- min_round: Validní odpovědi pouze pokud je tento nebo pozdější tah, jinak "too_early"
+
+Stav:
+GET na `/api/state?game=<jmeno_hry>&token=<token>&min_round=<min_round>`
+```json
+{
+	status: "ok"
+	round: <int> # Kolikáté je aktuální kolo (na počátku 0)
+	team_id: <int>
+	teams_count: <int>
+	time_to_response: <Optional[int]> # None v případě, že ho neznáme
+	state:
+	{
+		world: [[{
+			home_for_team: <Optional[int]>
+			occupied_by_team: <Optional[int]>
+			protected_for_team: <Optional[int]>
+			hill: <bool>
+			members: [{
+				type: "soldier" # Pro budoucí rozšiřování
+				team: <int>
+				id: <int> # Unikátní číslo v rámci týmu
+				remaining_rounds: <int> # vždy > 0
+			}]
+		}]]
+	}
+}
+
+nebo
+
+{
+	status: "working" nebo "too_early" # Server počítá následující stav nebo je některý z předchozích tahů, klient má počkat
+	wait: <float> # Jak dlouho má klient čekat, než se zeptá znovu
+}
+```
+
+Je zaručeno, že domeček mají uprostřed mapy
+
+
+Tah:
+POST na `/api/action?game=<jmeno_hry>&token=<token>&round=<round_id>`
+```json
+{
+	members: [
+		id: <int>
+		action: <Optional[str]>
+			# None -> čekej
+			# "left", "right", "up", "down"
+	]
+}
+```
+
+Odpověď na tah:
+```
+{
+	status: "ok"
+} # Vše v pořádku
+
+nebo
+
+{
+	status: "warning"
+	members: [ # seznam osob s chybou/varováním
+		id: <int>
+		description: <str>
+	]
+} # Tah jako celek se provede, chyba jen u některých osob
+
+nebo
+
+{
+	status: "error"
+	description: <str>
+} # Chyba celého tahu (např. nevalidní json, obsahuje povinné hodnoty ...)
+
+nebo
+
+{
+	status: "too-late"
+}
+```
+
+Požadavek na krok:
+POST na `/api/step?game=<jmeno_hry>&token=<token>`
+
+Odpověď:
+```
+{
+	status: "ok",
+}
+
+nebo
+
+{
+	status: "too_early"
+	wait: 5
+}
+```