Document the new /events API endpoint

This is a server-sent events stream which should be very convenient
for implementing the desired semantics of the game. For example, this
stream will allow the server to push out each character name to all
clients dur the phase of the game where characters are revealed
(without requiring clients to poll for characters nor agree on the
timing for displaying them).

diff --git a/api.text b/api.text
index f4ea703d3cd33d49f30845a5646eb54bae3f04d1..48a2eb6b072c499795d0d81a9451ce59ff37ee01 100644 (file)
--- a/api.text
+++ b/api.text
@@ -1,5 +1,57 @@
 Gameplay API endpoints (within a current game)
 ==============================================
 Gameplay API endpoints (within a current game)
 ==============================================

+/events
+
+    This is a server-sent events stream that allows the server to push
+    game-related events to clients. When a client connects to this API
+    endpoint the server will return a header that includes:
+
+       Content-type: text/event-stream
+       Connection: keep-alive
+       Cache-Control: no-cache
+
+    and will keep the connection open to return events.
+
+    The following event types will be returned by the server:
+
+       TYPE: players
+
+       WHEN: When a client first connects
+
+       PURPOSE: Describes all players in the game already
+
+       EXAMPLE:
+
+               event: players
+                data: [{"id":1,"name":"Carl"},{"id":2,"name":"Kevin"}]
+
+       TYPE: player-join
+
+       WHEN: When a player joins the game
+
+       EXAMPLE:
+
+               event: player-join
+                data: {"id":3,"name":"Richard"}
+
+       TYPE: player-leave
+
+       WHEN: When a player leaves the game
+
+       EXAMPLE:
+
+               event: player-leave
+               data: {"id":3}
+
+       TYPE: capture
+
+       WHEN: When one player captures another
+
+       EXAMPLE:
+
+               event: capture
+               data: {"captor": 2, "captee": 1}
+

 /register
 
     Method: POST
 /register
 
     Method: POST