Document the API and diagram the architecture

docs/api.md

@@ -0,0 +1,124 @@
+MOTH API
+=======
+
+Data encoding
+-----
+
+MOTH runs as an HTTP service,
+accepting standard HTTP `GET` and `POST`.
+
+Parameters may be encoded with standard `GET` query parameters
+(like `GET /endpoint?a=1&b=2`),
+or with `POST` as `application/x-www-form-encoded` data.
+
+
+Endpoints
+--------
+
+### `/state`
+
+Returns the current MOTH event state as a JSON object.
+
+#### Parameters
+* `id`: team ID (optional)
+
+#### Return
+
+```json
+{
+    "Config": {
+        "Devel": true/false
+    },
+    "Messages: "HTML to be rendered as broadcast messages",
+    "TeamNames": {
+        "self": "Requesting team name", # Only if regestered team id is a provided
+        "0": "Team 1 Name",
+        "1": "Team 2 Name",
+        ...
+    },
+    "PointsLog": {
+        [1602679698, "0", "category", 1], # epochTime, teamID, category, points
+        ...
+    },
+    "Puzzles": {
+        "category": [1, 2, 3, 6], # list of unlocked puzzles for category
+        ...
+    }
+}
+```
+
+### `/register`
+
+Registers a name to a team ID.
+
+This is only required once per team,
+but user interfaces may find it less confusing to users
+to present a "login" page.
+For this reason "this team is already registered"
+does not return an error.
+
+#### Parameters
+* `id`: team ID
+* `name`: team name
+
+#### Return
+
+An object inspired by [JSend](https://github.com/omniti-labs/jsend):
+
+```json
+{
+    "status": "success/fail/error",
+    "data": {
+        "short": "short description",
+        "description": "long description"
+    }
+}
+```
+
+### `/answer`
+
+Submits an answer for points.
+
+If the answer is wrong, no points are awarded 😉
+
+#### Parameters
+* `id`: team ID
+* `category`: along with `points`, uniquely identifies a puzzle
+* `points`: along with `category`, uniquely identifies a puzzle
+
+#### Return
+
+An object inspired by [JSend](https://github.com/omniti-labs/jsend):
+
+```json
+{
+    "status": "success/fail/error",
+    "data": {
+        "short": "short description",
+        "description": "long description"
+    }
+}
+```
+
+### `/content/{category}/{points}/{filename}`
+
+Retrieves static content associated with a puzzle.
+
+Every puzzle provides `puzzle.json`,
+a JSON object containing
+information about the puzzle such as the body 
+and list of attached files. 
+
+Parameters are all in the URL for this endpoint,
+so `curl` and `wget` can be used.
+
+#### Parameters
+* `{category}` (in URL): along with `{points}`, uniquely identifies a puzzle
+* `{points}` (in URL): along with `{category}`, uniquely identifies a puzzle
+* `{filename}` (in URL): filename to retrieve
+
+#### Return
+
+Raw file octets,
+with a (hopefully) suitable
+`Content-type` HTTP header field.