moth/docs/api.md

MOTHv3 API
==========

MOTH, by design, uses a small number of API endpoints.

Whenever possible,
we decided to push complexity into the client,
keeping the server as simple as we could make it.
After all,
this is a hacking contest.
If a participant finds a vulnerability in code running on their own machine,
the people running the server don't care.

Specification
=============

You make requests as HTTP GET query arguments:

    https://server/path/elements/api/v3/endpoint?var1=val1&var2=val2

The server returns a
[JSend](https://labs.omniti.com/labs/jsend) response:

    {
      "status": "success",
      "data": "Any JS data type here"
    }


Client State
============

The client (or user interacting with the client) needs to remember only one thing:

* teamId: the team ID used to register

A naive client,
like the one we used from 2009-2018,
can ask the user to type in the team ID for every submission.
This is fine.


Endpoints
=========

RegisterTeam(teamId, teamName)
-------------------------------

Register a team name with a team hash.

### Parameters

* teamId: Team's unique identifier (usually a hex value)
* teamName: Team's human-readable name

On success, no data is returned.
On failure, message contains an English explanation of why.


### Example

    https://server/api/v3/RegisterTeam?teamId=8b1292ca&teamName=Lexical+Pedants

    {
      "status": "success",
      "data": null
    }


GetState()
----------

Return all current state of the puzzle server.

### Return data

* 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

    https://server/api/v3/GetPuzzleList

    {
      "status": "success",
      "data": {
        "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"
        ]
      }
    }


GetPuzzle(category, points)
--------------------

Return a puzzle.

### Parameters

* category: name of category to fetch from
* points: point value of the puzzle to fetch


### Return data

* authors: List of puzzle authors
* hashes: list of djbhash values of acceptable answers
* files: dictionary of puzzle-associated filenames and their URLs
* body: HTML body of the puzzle


### Example

    https://server/api/v3/GetPuzzle?category=sequence&points=1

    {
      "status": "success",
      "data": {
        "authors": ["neale"],
        "hashes": [177627],
        "files": {
          "happy.png": "https://cdn/assets/0904cf3a437a348bea2c49d56a3087c26a01a63c.png"
        },
        "body": "<pre><code>1 2 3 4 5 _\n</code></pre>\n"
    }



SubmitAnswer(teamId, category, points, answer)
----------------------

Submit an answer to a puzzle.

### Parameters

* teamId: Team ID (optional: if ommitted, answer is verified but no points are awarded)
* category: category name of puzzle
* points: point value of puzzle
* answer: attempted answer


### Return Data

* epilog: HTML to display upon successfully answering the puzzle


### Example

    https://server/api/v3/SubmitAnswer?teamId=8b1292ca&category=sequence&points=1&answer=6

    {
      "status": "success",
      "data": {
        "epilog": "That's right: in base 10, 5 + 1 = 6."
      }
    }

SubmitToken(teamId, token)
---------------------

Submit a token for points

### Parameters

* teamId: Team ID
* token: Token being submitted


### Return data

* category: category for which this token awarded points
* points: number of points awarded
* epilog: HTML to display upon successfully answering the puzzle


### Example

    https://server/api/v3/SubmitToken?teamId=8b1292ca&token=wat:30:xylep-radar-nanox

    {
      "status": "success",
      "data": {
        "category": "wat",
        "points": 30,
        "epilog": ""
      }
    }