mirror of https://github.com/dirtbags/moth.git
125 lines
2.5 KiB
Markdown
125 lines
2.5 KiB
Markdown
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.
|