From b6dde238f6dabaa1c6852edb82635f1f6fb45056 Mon Sep 17 00:00:00 2001
From: Neale Pickett <neale@lanl.gov>
Date: Wed, 23 May 2018 20:37:49 +0000
Subject: [PATCH] Combine points log and open puzzles call

---
 docs/api.md | 61 +++++++++++++++++++++--------------------------------
 1 file changed, 24 insertions(+), 37 deletions(-)

diff --git a/docs/api.md b/docs/api.md
index 45a3b3d..44f65f0 100644
--- a/docs/api.md
+++ b/docs/api.md
@@ -67,14 +67,19 @@ On failure, message contains an English explanation of why.
     }
 
 
-GetPuzzleList()
----------------
+GetState()
+----------
 
-Return all currently-open puzzles.
+Return all current state of the puzzle server.
 
 ### Return data
 
-* puzzles: dictionary mapping from category to a list of point values.
+* puzzles: dictionary mapping from category to one of the following:
+  * list of point values currently open
+  * URL to puzzle root (intended for token-based puzzles)
+* teams: mapping from anonymized team ID to team name
+* log: list of (timestamp, team number, category, points)
+* notices: list of HTML broadcast notices to display to the user
 
 
 ### Example
@@ -87,7 +92,21 @@ Return all currently-open puzzles.
         "puzzles": {
           "sequence": [1, 2],
           "codebreaking": [10],
-        }
+          "wopr": "https://appspot.com/dooted-bagel-8372/entry"
+        },
+        "teams": {
+          "0": "Zelda",
+          "1": "Defender"
+        },
+        "log": [
+          [1526478368, "0", "sequence", 1],
+          [1526478524, "1", "sequence", 1],
+          [1526478536, "0", "nocode", 1]
+        ],
+        "notices": [
+          "<a href=\"https://appspot.com/dooted-bagel-8372/entry\">WOPR category</a> is now open",
+          "Event closes at 18:00 today, and will resume tomorrow at 08:00"
+        ]
       }
     }
 
@@ -127,38 +146,6 @@ Return a puzzle.
     }
 
 
-GetPointsLog()
----------------
-
-Return the entire points log, and team names.
-
-### Return data
-
-* teams: mapping from team number (int) to team name
-* log: list of (timestamp, team number, category, points)
-
-Note: team number may change between calls.
-
-
-### Example
-
-    https://server/api/v3/GetEventsLog
-
-    {
-      "status": "success",
-      "data": {
-        "teams": {
-          0: "Zelda",
-          1: "Defender"
-        },
-        "log": [
-          [1526478368, 0, "sequence", 1],
-          [1526478524, 1, "sequence", 1],
-          [1526478536, 0, "nocode", 1]
-        ]
-      }
-    }
-
 
 SubmitAnswer(teamId, category, points, answer)
 ----------------------