From: Carl Worth <cworth@cworth.org>
Date: Sun, 10 May 2020 16:51:24 +0000 (-0700)
Subject: Document the new /events API endpoint
X-Git-Url: https://git.cworth.org/git?p=lmno-api;a=commitdiff_plain;h=39b74cde47375adaeacc33507a2173b63e3de10c

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 f4ea703..48a2eb6 100644
--- a/api.text
+++ b/api.text
@@ -1,5 +1,57 @@
 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