Developer API

• General
• HTTP GET Methods
  • /api/getusers.php
  • /api/createuser.php
  • /api/deleteuser.php
  • /api/deletegame.php
  • /api/setplayerstate.php
  • /api/getgames.php
• HTTP POST Methods
  • /api/creategame.php
  • /api/postgamestate.php

General

The web site uses HTTP POST and GET methods to communicate with other software. The response data is encoded as JSON. The POST requests will also carry the parameters as JSON in the request body. You need to understand the concept of the User ID before you read on. The API functions are located in the subfolder /api/ of the web site host (e.g. http://triplea.yourserver/api/...).

All API methods will response with a JSON object. This JSON object will always look like this:

{ "success": true/false, "data": ... }

If "success" is false, "data" will contain an error message. If "success" is true, method-dependent response information is returned in "data".
If the response message is not valid JSON, an internal error occurred.

HTTP GET Methods

/api/getusers.php

This method does not take any parameters and returns a list of all users, which are registered at the web site. Each user name is returned as an item in a JSON array.

Example:
If Rita, Sam and John D. are registered at the web site, this method would return the text:

{ "success": true, "data": ["Rita", "Sam", "John D."] }

/api/createuser.php

This method can be used to create users through the API. It takes parameters "id", "name" and "email", where "id" is optional. The given "id" is the User ID of the one who tries to create a new user. If creating users is restricted to a (few) registered users, the "id" parameter becomes neccessary.

Example:
/api/createuser.php?id=38761abc6eb8f1a0098ccef4a&name=Johns%20brother&email=johnb@example.com

This tries to create the user with name "Johns brother". On success the response will contain the new user ID:

{ "success": true, "data": "8720abc5e91ffe4a983b77fc4" }

/api/deleteuser.php

This method can be used to delete users through the API. It takes parameters "id" and "name". The given "id" is the User ID of the one who tries to delete the user specified in "name". Existing games where the deleted user was assigned will break. Deleting users is probably restricted to a (few) registered users. Deleting yourself is always allowed (if the given 'id' and 'name' belong together).

Example:
/api/deleteuser.php?id=38761abc6eb8f1a0098ccef4a&name=Johns%20brother

This tries to delete the user with name "Johns brother". On success the response data will be null:

{ "success": true, "data": null }

/api/deletegame.php

This method can be used to delete a game through the API. It takes parameters "id" and "gamename". The given "id" is the User ID of the one who tries to delete the game specified in "gamename". The game will then just disappear and cannot be restored. Deleting games is probably restricted to a (few) registered users.

Example:
/api/deletegame.php?id=38761abc6eb8f1a0098ccef4a&gamename=Johns%20New%20Game

This tries to delete the game with name "Johns New Game". On success the response data will be null:

{ "success": true, "data": null }

/api/setplayerstate.php

This method can be used to set the current state of a player within a game, for example to mark that this player has surrendered. It takes the User ID ("id"), the name of the target game ("gamename") and the new state ("state"). This will mark all parties played by the given User ID with the given state in the specified game. If you want to set the state for only a specific party, you can use an optional additional parameter 'player'. Users can only change the state of their own players. Currently, the valid states are "OK" and "Surrender".

Example:
/api/setplayerstate.php?id=38761abc6eb8f1a0098ccef4a&gamename=Johns%20New%20Game%state=Surrender

This will mark all players player by the user with the given ID in game "Johns New Game" with "Surrender". On success the response data will be null:

{ "success": true, "data": null }

/api/getgames.php

This method does not take any parameters and returns a list of all games, which are currently existing at the web site. For each game, the set of players is returned, see the example.

Example:

{
  "success": true,
  "data": [
    {
      "gamename": "Johns New Game",
      "players":
        {
         "Russians": {"username": "Rita",   "state": "OK"},
         "Germans":  {"username": "Claus",  "state": "OK"},
         "Britain":  {"username": "Sam",    "state": "OK"},
         "Japanese": {"username": "John D.","state": "Surrender"},
         "Americans":{"username": "Rita",   "state": "OK"}
        }
    },
    {
      "gamename": "Welcome n00bs",
      "players":
        {
          ...
        }
    }
  ]
}

HTTP POST Methods

/api/creategame.php

This method is used to create games at the web site. It takes a JSON object for the POST request message body which looks like this:

{
  "id": "38761abc6eb8f1a0098ccef4a",
  "gamename": "Johns New Game",
  "players": {
    "Russians": "Rita",
    "Germans": "Claus",
    "Britain": "Sam",
    "Japanese": "John D.",
    "Americans": "Rita"
  }
}

• id -- The ID of the user, which is creating the game.
• gamename -- The name of the new game. Currently, you must use only ASCII characters which are allowed in file names.
• players -- A mapping from parties to user names.
  The method returns a JSON response object as written in "General" above.

The method will fail:

• if one of the parameters was not set
• if the given user id is unknown
• if the given user id is not allowed to create games
• if a game with the specified gamename was already created
• if the mapping in players is empty

/api/postgamestate.php

Whenever a party completes his turn and wants to send the new game state to this web site, the 'postgamestate' method has to be used. It takes a JSON object for the POST request message body, which looks like this:
It takes the following JSON object for the POST request message body:

{
  "id": "8720abc5e91ffe4a983b77fc4",
  "gamename": "Johns New Game",
  "player": "Russians",
  "round": 1,
  "production": { "Axis": 90, "Allies": 110 },
  "summary": "Ritas turn summary",
  "savegame": "SGVsbG8gV29ybGQh..."
}

• id -- The ID of the user, which just completed his turn.
• gamename -- The name of the associated game.
• player -- The name of the party, which has just moved. (This is used to check consistency and prevent unintended savegame uploads.)
• round -- The round number of the move, which has just been done. (This is used to check consistency and prevent unintended savegame uploads.)
• production -- The production stats as a mapping from team names to production units.
• summary -- A textual summary of the turn. This is currently not displayed at the web site (although is must be sent).
• savegame -- The base64 encoded data of the savegame file.