From 366bac0a9b0f26218d5d78b7ba547717fb07a987 Mon Sep 17 00:00:00 2001
From: Carl Worth <cworth@cworth.org>
Date: Sun, 24 May 2020 09:09:15 -0700
Subject: [PATCH] empires 0.7: Add endpoints to add, remove, and list
 spectators

The endpoints are:

  POST /spectator
  DELETE /spectator/<ID>
  GET /spectators

The addition of a separate notion of spectators from players gives us
two advantages:

  1. People can just watch if they want to

  2. A client can naturally separate the selection of the player's name
     (to create the spectator, join the game, see who else is in, etc.),
     from the selection of the player's character. This separation should
     avoid some confusion we saw in playtesting where players confused
     which name was which.
---
 empires.txt | 44 ++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 42 insertions(+), 2 deletions(-)

diff --git a/empires.txt b/empires.txt
index 42d4f0e..da590a3 100644
--- 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" } ]
 
-- 
2.43.0