empires 0.7: Add endpoints to add, remove, and list spectators

[lmno-api] / empires.txt

diff --git a/empires.txt b/empires.txt
index 42d4f0ee459dbecc99f313da8557fbf522f8a826..da590a3039521c24196acbc02840b3bd1d3d28c7 100644 (file)
--- a/empires.txt
+++ b/empires.txt
@@ -1,6 +1,6 @@
 Empires Game Protocol
 =====================
-Version: 0.6
+Version: 0.7
 
 For a specific game the following API endpoints are defined.
 (Note: Only the trailing portion of the API URI is provided here.
@@ -114,6 +114,28 @@ For a specific game the following API endpoints are defined.
 
     Behavior: Removes an existing player with the given ID
 
+/spectator
+
+    Method: POST
+
+    Behavior: Add a new spectator with the given name, assigning and
+    returning an ID for the spectator.
+
+    Note: If the client supports cookies and has previously set a
+    nickname in the current session via the upper-level /profile API,
+    then the name can be omitted from the data here and the profile
+    nickname will be used instead.
+
+    Example data: { "name": "Carl" }
+
+    Example return data: 23
+
+/spectator/<ID>
+
+    Method: DELETE
+
+    Behavior: Remove an existing spectator with the given ID
+
 /reveal
 
     Method: POST
@@ -177,12 +199,30 @@ For a specific game the following API endpoints are defined.
                    { "id": 5, "captures": [] },
                    { "id": 6, "captures": [] } ]
 
+/spectators
+
+    Method: GET
+
+    Behavior: Gets a list of all spectators. A spectator is someone
+    who has started viewing the game (and stated their own
+    name) but isn't directly involved in the game.
+
+    Example data: [ { id: 1, name: "Richard"}, { id: 2, name: "Nancy"} ]
+
+    Note: The IDs of spectators and players are unrelated. If a person
+    initially joins as a spectator and then later joins the game as a
+    player, an unrelated player ID will be generated. From the
+    server's point of view, the events of a spectator leaving and a
+    player joining that happens to have the same name---those two
+    events have nothing to do with each other.
+
 /players
 
     Method: GET
 
     Behavior: Gets a list of all the player objects (without their
-    character names)
+    character names). A player is someone who is registered a
+    character choice to participate in the game.
 
     Example data: [ { id: 1, name: "Carl" }, { id: 2, name: "Kevin" } ]