68 lines
2.4 KiB
Markdown
68 lines
2.4 KiB
Markdown
# Bot-Man-Toe Specification
|
|
|
|
This document describes how a Bot-Man-Toe server or client is supposed to
|
|
behave.
|
|
|
|
## Terminology
|
|
|
|
A **server** is a REST API server that hosts a player willing to play games.
|
|
A **client** can feed it a game's state through a request with a JSON body,
|
|
and the server may respond with an action they wish to take.
|
|
|
|
While each API request is completely stateless and memoryless, it is typical
|
|
for clients to use the server to play full games.
|
|
|
|
## Discovery
|
|
|
|
Each server has a uniquely identifying URL at which they can be addressed.
|
|
|
|
### /
|
|
|
|
At the root of the URL, the client may send a GET request. The server should
|
|
ignore the JSON body, and respond with a profile detailing which game(s) the
|
|
server is willing to play.
|
|
|
|
#### 200 Response
|
|
|
|
The server issues this response to indicate that it's a Bot-Man-Toe server.
|
|
It'll offer some details, preferences and clarifications about itself that the
|
|
client may use.
|
|
|
|
For example, they may choose a favourite color they'd like to be displayed in,
|
|
indicate their favourite type of food or restrict what kind of roles it can
|
|
play in certain games. (e.g. it can only play as white in chess)
|
|
|
|
| Field | Type | Description |
|
|
| ----- | ---- | ----------- |
|
|
| name | string | The preferred name of the server in games. Clients may use this to create scoreboards. |
|
|
| games | {string:Game} | Collection of supported games. The key is the game's identifying API endpoint route, and the value is the server's profile information for that game. |
|
|
|
|
Notes:
|
|
|
|
- Clients should treat any unrecognized top-level fields as opaque metadata.
|
|
- Clients should ignore malformed entries inside `games` rather than failing the whole discovery step, unless the root payload itself is invalid.
|
|
- Discovery requests should be made against the root endpoint with a plain `GET`; the server may ignore the request body if one is present.
|
|
|
|
Some other metadata might be provided. When providing custom information, you
|
|
are recommended to provide this information in a way that respects the Java
|
|
package namespace guidelines.
|
|
|
|
```json
|
|
{
|
|
"name": "My self-built AI!!!1!",
|
|
"games": {
|
|
"/snake": {
|
|
"snake_color": "red",
|
|
"snake_face": "silly"
|
|
},
|
|
"/tic-tac-toe": {},
|
|
"/chess": {
|
|
"preferred_color": "white"
|
|
}
|
|
},
|
|
"org.example.my-custom-data": "foobarbaz",
|
|
"org.example.some-more-data": {}
|
|
}
|
|
```
|
|
|