Specify an initial REST API for playing a game of Empires

[lmno-api] / api.text

diff --git a/api.text b/api.text
new file mode 100644 (file)
index 0000000..91a390c
--- /dev/null
+++ b/api.text
@@ -0,0 +1,83 @@
+Gameplay API endpoints (within a current game)
+==============================================
+/register
+
+    Method: POST
+
+    Behavior: Adds a new player with "name" and "character" and assigns an id. Also will add a new empire with empty "captured" array
+
+    Example data: { "name": "Carl", "character: "Elvis" }
+
+/deregister/<ID>
+
+    Method: POST
+
+    Behavior: Removes an existing player with the given ID
+
+/reset
+
+    Method: POST
+
+    Behavior: Removes all players (bulk deregister)
+
+/restart
+
+    Method: POST
+
+    Behavior: Eliminates all current empire ownership so the existing
+    players can start a new game
+
+/capture/<ID1>/<ID2>
+
+    Method: POST
+
+    Behavior: Indicate that empire ID1 has now captured ID2
+
+/escape/<ID>
+
+    Method: POST
+
+    Behavior: Indicate that empire ID is no longer captured (undoing a
+    previous /capture)
+
+/characters
+
+    Method: GET
+
+    Behavior: Returns a lists of all character names (in alphabetical order)
+
+    Example data: [ "Einstein", "Elvis", "Fred Flintstone" ]
+
+/empires
+
+    Method: GET
+
+    Behavior: Shows which empires have been captured by other empires
+
+    Example data [ { "id": 1, "captured": [] },
+                   { "id": 2, "captured": [1] },
+                   { "id": 3, "captured": [4, 5, 6] },
+                   { "id": 4, "captured": [2] },
+                   { "id": 5, "captured": [] },
+                   { "id": 6, "captured": [] } ]
+
+/players
+
+    Method: GET
+
+    Behavior: Gets a list of all the player objects (without their
+    character names)
+
+    Example data: [ { id: 1, name: "Carl" }, { id: 2, name: "Kevin" } ]
+
+/players/<id>
+
+    Method: GET
+
+    Behavior: Get a single player by its id
+
+Server
+======
+There's a sample server available at: https://families.cworth.org/
+
+We plan to move this to https://empires.cworth.org at some point.