API Specification

The client is going to interact with the game by sendin HTTP requests to the server. Those requests are going to be returned with a JSON response. All the possible actions a player can do are going to be done through the API. He can get informations about the state of the game like the ranking of the best players or do actions like building units and attacking another player.

Here is a list of all the possible HTTP requests a player can do, not including the authentification specific routes.

For all of these endpoints the user must have a valid session_id cookie, except GET /game/ranking which is a public ranking.

GET /

Take no parameter and return a welcome message containing the number of players registered.

  [
      "Welcome to my game which currently has 2 players !"
  ]

GET /game/ranking

Take no parameter and return all the players ranked by the amount of gold they have.

[
    [
        {
            "username": "user1",
            "gold": 4110
        },
        {
            "username": "user2",
            "gold": 222
        }
    ]
]

GET /game/village

Take no paramater and return the village informations of the connected player

[
    {
        "id": 31,
        "name": "testoo",
        "x_position": 50,
        "y_position": 96,
        "gold": 4110,
        "level": 1,
        "space_capacity": 5,
        "player_id": 43,
        "army_id": 21
    }
]

POST /game/create_building

Take no paramater and allow the user to create gold mines, in the future it will take a paramater in order to create different kind of buildings.

This is the message if it is a success:

  {
      "success": true
  }

You can also get different kind of errors like this one if the user does not have enough gold or space:

  {
      "success": false,
      "error": "not enough ressources"
  }

POST /game/upgrade_building

Take the id of the building to upgrade, verify that the person who made the request is indeed the owner of the building and that he has enough gold and space to upgrade it.

This is the message if it is a success:

  {
      "success": true
  }

You can also get different kind of errors like this one if the player who made the request is not the owner of the building:

  {
      "success": false,
      "error": "you are not the owner of this building"
  }

POST /game/buy_units

The typical attack request will have this structure:

  {
      "nb_ranged": 100,
      "nb_cavalry": 100,
      "nb_infantry": 100
  }

This is the message if it is a success:

  {
      "success": true
  }

The operation can fail if the player does not have enough gold to buy the desired units.

  {
      "success": false,
      "error": "not enough gold"
  }

POST /game/attack

The typical attack request will have this structure:

  {
      "target_village_id": 32,
      "source_village_id": 31,
      "nb_ranged": 100,
      "nb_cavalry": 100,
      "nb_infantry": 100
  }

All kinds of check are going to be ran, like if the player attack himself, if the target village is not his and if he has enough units to attack.

This is the message if it is a success:

  {
      "success": true
  }

And this is an example of an error message if the player does not have enough units to attack:

  {
      "success": false,
      "error": "not enough units to attack"
  }

Authentification