moth/docs/api.md

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

{
    "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:

{
    "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:

{
    "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.