Gamesman Web Documentation

Note: This documentation is for Gamesman Web, not the Liberation API.

REST API

The Gamesman Web API is a small interface between the front-end user interfaces and the back-end move-value databases. It comprises a handful of stateless functions, cleanly separating the front-end from the back-end. At the same time, the API is quite thin, and allows for game-specific arguments.

Invoking a Gamesman Web function is the same as issuing an HTTP GET request. We use matrix URIs instead of query parameters due to their flexibility and simplicity to both emit and parse. The base URI for all API calls is http://nyc.cs.berkeley.edu:8080/gcweb/service/gamesman/puzzles/internal-game-name/. (Why do we have puzzles in there? I don't know. We should probably remove that.) internal-game-name is the internal name of the game you'd like to play. There's no table of these right now, but the person writing the solver and registering the game with Gamesman Web will know what it is. It's never an arbitrary string, though; for example, Connect Four's internal name is connect4 and Triple Cross's is tcross.

An example of an API call is: http://nyc.cs.berkeley.edu:8080/gcweb/service/gamesman/puzzles/connect4/getMoveValue;board=%20%20;width=1;height=2;pieces=1, which asks for the value of the empty board (denoted by two spaces, URI-encoded as %20%20) that has a width of one and a height of two in a game of Connect Four that requires only one piece in a row to win (Connect One? Exciting, I know.).

Return values are encoded using JSON, a light, readable, and easy-to-parse format. It's less verbose than XML and there are just as many parsers for it. In fact, JSON is simply a subset of JavaScript code, which means that any JavaScript interpreter can parse a JSON string into a JavaScript object for you. (Python interpreters also do a reasonable job, and there's the json module as well.) All JSON responses include a property named status, whose value should either be ok or error. This lets you immediately know if something went wrong; you might find a message property that explains the error. When successful, there's another top-level property called response, which contains the return value of the function you called. The documentation on function return values talks within the context of this response field unless noted otherwise.

An example of a JSON response to a successful getNextMoveValues API call is:

{"status": "ok",
 "response": [
   {"board": "X        ", "remoteness": 9, "value": "tie", "move": "0"},
   {"board": " X       ", "remoteness": 9, "value": "tie", "move": "1"},
   {"board": "  X      ", "remoteness": 9, "value": "tie", "move": "2"}
]}

This is the response to a request for the move-values of the initial board's children in a game of three-by-three Connect Four. As you can see, the response is easy to read, provided you understand the terminology.

getMoveValue

Retrieves the value of a specified board. This function is usually called at the beginning of a game to learn about the initial board.

Parameters

NameDescriptionDefault if Unspecified
board A string representing the current board. This varies from game to game, and you'll have to speak with the game implementor to find out the format since they'll eventually receive this string and need to parse it. Empty string (this probably isn't very useful)
width The width of the board. Defaults to zero if left unspecified. Zero
height The height of the board. Zero
miscellaneous You can include as many extra arguments as you'd like. For example, to specify the number of pieces in a row needed to win in Connect Four, you might include pieces=4. Empty string

Return Value

The return value is a JSON object with information about the specified board.

NameDescription
board The string representation of the board whose value is described in the response. This is the same string as the one in the request.
value Whether the board is a win, lose, tie, or draw for the current player. This field is absent if move-values are unavailable.
remoteness The fewest number of moves it will take to reach a primitive board with the specified value, assuming optimal play. (In the case of a losing position, this is the greatest number of moves until the current player finally loses.)

getNextMoveValues

Retrieves the values of all children of the specified board, almost as if getMoveValue were called for each of the children.

Parameters

Same as those for getMoveValue.

Return Value

The return value is a list of JSON objects, each similar to the result of a call to getMoveValue. However, these move-values include extra information.

NameDescription
move The string representation of the move that will lead from the parent board (the board specified in the request) to the child board (the board included in the response). This is highly game-specific and dependent on the back-end. For example, a move in Connect Four is represented as the number of the column in which the piece was dropped.