Bot-Man-Toe/spec

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.

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