api.thirdparty

Aaron Dalton edited this page Jun 9, 2018 · 1 revision

Games and AIs should be implemented as web applications and can be hosted anywhere. How you implement the interface is up to you (CGI, binding something to a specific port, whatever floats your boat). Below is an explanation of what parameters can be expected by the application and what return values are required. All communication will happen via POST, the payload will be sent as application/x-www-form-urlencoded, and the connection should be SSL/TLS secured.

All the schemas can be browsed at https://www.abstractplay.com/schemas. The naming scheme should be obvious.

Games

All requests will contain a mode parameter that will match one of the following values:

  • ping
  • metadata
  • init
  • move
  • archive
  • render (optional)

ping

The AbstractPlay service will contact third-party games periodically. Probably no more than hourly. Nothing is determined yet, and the polling period could be adjusted on a per-game basis. This way we can detect problems and alert players.

There are a few expected responses:

  • Any HTTP error code returned (most likely 404, 500, perhaps 503) will be stored and the game will be marked as unavailable.
  • If you have intentionally taken the game offline for maintenance, then emit a 503 and briefly explain the issue. The code and message will be stored and the game will be marked as unavailable.
  • Otherwise, emit 200 and in the body of the response, include in the body JSON matching the schema.

The state value is opaque to the server. This is how you signal the server that changes have been made to your game code. When the system sees that your state has changed, it will follow up with a metadata request to update its information. See the "metadata" section for more details.

metadata

When requested (usually in response to a state change signalled during a ping), return a 200 and JSON in the body matching the schema.

  • state (see the ping mode for a description)
  • version is a simple integer and should only be changed if you are breaking backwards compatibility. The version number is attached to each new game created. Your code should be able to handle older versions as long as possible! When playing asynchronously, games can take months to complete. Please do not ruin games in progress. Consistent problems with backwards compatibility could result in the game being removed from the system.
  • maxplayers is a simple integer representing the maximum number of players your game supports.
  • description is a block of Markdown-encoded text (maximum length of 65,535 characters) that describes the game and can include rules and images. Like blogs, there is a continuation mark (TBD) to separate the short summary from the full rule set.
  • changelog is a block of Markdown-encoded text (maximum length of 65,535 characters) that describes how the code has changed over time (bug fixes, new versions, etc.)

init

This is how new games are created. You receive the following parameters and you are expected to return either a "400 Bad Request" if we screwed up or a "200 OK" along with a JSON body that adheres to the same schema as the move request.

  • variants: A list of selected variants (not including the system-wide variants). You are expected to store necessary variants in your game states as they won't be transmitted again.
  • players: A list of userids. In games where seating order is significant, it is expected that the game script will seat the players in the order provided. The server will take care of randomizing seating (the usual) or honouring seating requests on a challenge-by-challenge basis.

move

You'll receive the following parameters:

  • userid: the player who submitted the move
  • move: a text representation of the move the player made
  • state: the current game state of record

If an error occurs during processing, return a "400 Bad Request" and put some human-readable message in the body. That message will be conveyed to the user and hopefully we'll figure things out.

Otherwise, you are expected to return a "200 OK" and a JSON body matching the schema.

archive

The server will send you all the game states of a given game. You must return a single JSON object representing the entire game that can be archived. Player rankings and ratings are based on the analysis of these archive records.

The schema is modelled after chess PGN files and is currently in heavy development.

Periodically, old games and all their associated data (e.g., states and chats) will be purged, leaving only these archive reports.

render

This may disappear. I may do this on the server side. The idea is to be able to easily render the game space in different formats. I anticipate supporting the following modes:

  • image (presumably PNG)
  • text (monospaced for email)

AIs

AIs are also called as CGI scripts and can be hosted anywhere. They receive login credentials so they can submit their moves like any other player.

All communication with the AI will be via POST and will always contain a mode parameter. There are only two modes you need to expect:

  • ping: If your AI is active, just return 200. Also include a JSON body with the following schema. If it's intentionally down for maintenance, return a 503 with a message in the body, which will be stored. Any other HTTP error codes and message will be stored and the AI will be marked as unavailable.
  • metadata: If in response to a ping the server notices that the state has changed, it will follow up with this request to get the updated information. Your response should adhere to the schema.
  • yourturn: This is how your AI will know it's its turn. You can also poll the API, but the goal is to reduce unnecessary server load and bandwidth. The gamestate parameter is a representation of the most recent game state for you to consider and base your move on. You are expected to do any basic integrity checks (do you understand the given game state?) and return a "400 Bad Request" with a helpful message or return "202 Accepted" and immediately disconnect. You can then take all the time you need to consider your move. You are then expected to use your credentials to submit your move as usual. AIs are subject to game clocks as usual.
You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.