moth/docs/api.md

218 lines
4.1 KiB
Markdown
Raw Normal View History

2018-05-23 11:29:32 -06:00
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/to/endpoint?var1=val1&var2=val2
The server returns a
[JSend](https://labs.omniti.com/labs/jsend) response:
{
2018-05-23 12:06:47 -06:00
"status": "success",
"data": "Any JS data type here"
2018-05-23 11:29:32 -06:00
}
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
2018-05-23 11:29:32 -06:00
* 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
2018-05-23 11:29:32 -06:00
https://server/RegisterTeam?teamId=8b1292ca&teamName=Lexical+Pedants
2018-05-23 11:29:32 -06:00
{
2018-05-23 12:06:47 -06:00
"status": "success",
"data": null
2018-05-23 11:29:32 -06:00
}
GetPuzzleList()
---------------
Return all currently-open puzzles.
### Return data
2018-05-23 11:29:32 -06:00
* puzzles: dictionary mapping from category to a list of point values.
### Example
2018-05-23 11:29:32 -06:00
https://server/GetPuzzleList
{
2018-05-23 12:06:47 -06:00
"status": "success",
"data": {
2018-05-23 11:29:32 -06:00
"puzzles": {
"sequence": [1, 2],
"codebreaking": [10],
}
}
}
GetPuzzle(category, points)
--------------------
2018-05-23 11:29:32 -06:00
Return a puzzle.
### Parameters
2018-05-23 11:37:29 -06:00
* category: name of category to fetch from
* points: point value of the puzzle to fetch
### Return data
2018-05-23 11:29:32 -06:00
* 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
2018-05-23 11:29:32 -06:00
https://server/GetPuzzle?category=sequence&points=1
{
2018-05-23 12:06:47 -06:00
"status": "success",
"data": {
2018-05-23 11:29:32 -06:00
"authors": ["neale"],
"hashes": [177627],
"files": {
"happy.png": "https://cdn/assets/0904cf3a437a348bea2c49d56a3087c26a01a63c.png"
},
"body": "<pre><code>1 2 3 4 5 _\n</code></pre>\n"
}
GetPointsLog()
---------------
2018-05-23 11:29:32 -06:00
Return the entire points log, and team names.
### Return data
2018-05-23 11:29:32 -06:00
* 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
2018-05-23 11:29:32 -06:00
https://server/GetEventsLog
{
2018-05-23 12:06:47 -06:00
"status": "success",
"data": {
"teams": {
2018-05-23 11:29:32 -06:00
0: "Zelda",
1: "Defender"
},
2018-05-23 12:06:47 -06:00
"log": [
2018-05-23 11:29:32 -06:00
[1526478368, 0, "sequence", 1],
[1526478524, 1, "sequence", 1],
[1526478536, 0, "nocode", 1]
]
}
}
SubmitAnswer(teamId, category, points, answer)
----------------------
2018-05-23 11:29:32 -06:00
Submit an answer to a puzzle.
### Parameters
2018-05-23 11:37:29 -06:00
* 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
2018-05-23 12:12:32 -06:00
* epilog: HTML to display upon successfully answering the puzzle
### Example
2018-05-23 11:29:32 -06:00
https://server/SubmitAnswer?teamId=8b1292ca&category=sequence&points=1&answer=6
{
2018-05-23 12:06:47 -06:00
"status": "success",
"data": {
2018-05-23 12:12:32 -06:00
"epilog": "That's right: in base 10, 5 + 1 = 6."
}
2018-05-23 11:29:32 -06:00
}
SubmitToken(teamId, token)
---------------------
2018-05-23 11:29:32 -06:00
Submit a token for points
### Parameters
2018-05-23 11:37:29 -06:00
* teamId: Team ID
* token: Token being submitted
### Return data
2018-05-23 11:29:32 -06:00
* category: category for which this token awarded points
* points: number of points awarded
2018-05-23 12:12:32 -06:00
* epilog: HTML to display upon successfully answering the puzzle
2018-05-23 11:29:32 -06:00
### Example
2018-05-23 11:29:32 -06:00
https://server/SubmitToken?teamId=8b1292ca&token=wat:30:xylep-radar-nanox
{
2018-05-23 12:06:47 -06:00
"status": "success",
"data": {
"category": "wat",
2018-05-23 12:09:06 -06:00
"points": 30,
2018-05-23 12:12:32 -06:00
"epilog": ""
2018-05-23 11:29:32 -06:00
}
}