mirror of
https://github.com/dirtbags/moth.git
synced 2025-01-10 17:05:07 -07:00
Document the API and diagram the architecture
This commit is contained in:
parent
f7d58846e4
commit
71215ae64e
2 changed files with 124 additions and 0 deletions
124
docs/api.md
Normal file
124
docs/api.md
Normal file
|
@ -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.
|
BIN
docs/system-arch.png
Normal file
BIN
docs/system-arch.png
Normal file
Binary file not shown.
After (image error) Size: 86 KiB |
Loading…
Reference in a new issue