API.md 4.5 KB

API

This document explains how a client should use server's API. The API lets a client:

  • See a list of current open games in the lobby.
  • Register for a nick in order to enter the lobby and play games.
  • Chat either in lobby or in game.
  • Select a game to join or spectate.
  • Start a new game, either private or public.
  • "Play" a game.

If a client has the special admin key, it can perform the following actions:

  • Delete a registered nick.
  • Change token of a registered nick to a random one.
  • See token of a registered nick.
  • See logs.
  • Unban/Ban an IP or IPs.
  • Force end a game.
  • Broadcast a chat message to lobby and all games.
  • Restart or Shutdown server.

Output is in JSON all the time!

All APIs requiring a token will return the following JSON when the given token is invalid or does not exist at all:

{"error": "Invalid or non-existence token!"}

Normal client

register {nick}

Outputs an access token which later should be used to access other APIs. Token is always a string with length of 12 which is alphanumeric. The admin nick is special and no one can register it.

Example:

{"token": "TOKEN"}

It may throw back an error instead of token saying the nick is already taken:

{"error": "The nick Far is already registered"}

lobby {token}

Returns a list of current open public games some client can join.

[
  {"nick": "Far"},
  {"nick": "Bob"}
]

nick shows the nick of starter of game.

join {token} {nick} [code] [spectate]

Joins the game which player with the given name has started. code is required only if the game is private and for public games it is ignored if given. A client may start a game by giving its own nick optionally with a code to make the game private. spectate should be provided only if a client wants to just watch the game. Output:

{"msg": "Successfully joined {nick}'s game", "char": "X"}

It would return errors if the client has already joined a game or the code for private game is incorrect:

{"error": "You have already joined a game"}
{"error": "Incorrect code for private game"}

Also for spectating:

{"error": "Game does not exist"}

leave {token}

Leaves a current joined game. The client can leave the game either if the game has started or not. It will return an error if the client has not joined a game:

{"error": "You have not joined a game"}

chat {token} [msg] [timeout]

Returns a list of last 16 messages in the lobby. It will return messages in the current game if the client has joined a game.

Server will wait timeout seconds if this argument is provided and will respond immediately otherwise.

Server will send msg to the lobby or current game if this argument is provided and this client's message will be the last of those 16 messages.

The maximum length of each message is Y characters and a client cannot send more than one messages every X seconds. X and Y are specified in server's config.

Sample output:

[
  {"Far": "Hi!"},
  {"Joe": "Lo!"}
]

Errors:

{"error": "Wait a little and retry sending message!"}
{"error": "Too long message. Max length is Y"}

play {token} {type} {coordinates}

When the client has joined a game, it has started and the turn is player's, send the next player's move. type is either "swap" or "place".

  • swap: coordinates is X,Y each numbers from 1 to 9. X and Y shouldn't be the same number or an error will be thrown back.

  • place: coordinates is X,Y each from 1 to 9 specifying, in order, the tile in the global/outer board and the tile in a local/inner board. Will thrown back an error if the selected place is not blank.

 1 | 2 | 3
-----------
 4 | 5 | 6
-----------
 7 | 8 | 9

Admin client APIs

ban {token} {IPs}

Bans a list of IPs separated by a comma ,.

unban {token} {IPs}

Unbans a list of IPs separated by a comma ,.

shutdown {token}

Shuts the server down.

restart {token}

Restarts the server.

token {token} {nick} [new]

See nick's token or change it to a random new one if new is true.

{"error": "No such nick"}
{"token": "TOKEN"}

end {token} {nick}

Force ends a game.

{"error": "No such game"}

broadcast {token} {msg}

Broadcasts a msg to all games and lobby chat. Does not return anything if successful.

delete {token} {nick}

Deletes nick from database.

{"error": "No such nick"}

logs {token} [X]

THIS DOES NOT RETURN JSON! It is actually output of tail -n X=100 server.log