Specify an initial REST API for playing a game of Empires

This is an initial draft which is hopefully adequate for playing a
game. At this point we haven't implemented this on either client or
server side so we anticipate revisiting this after we implement and
learn any deficiences.

Thanks to Kevin Worth for designing this with me today.

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.