Note: This documentation is for Gamesman Web, not the Liberation 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.
Name | Description | Default 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 |
The return value is a JSON object with information about the specified board.
Name | Description |
---|---|
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.
Same as those for getMoveValue
.
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.
Name | Description |
---|---|
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. |