RESTful API

Endpoints

`POST /api/games`

To create games

Parameters

All parameters are optional

{ "rows": [#-OF-ROWS]
, "cols": [#-OF-COLS]
, "ticktime": [#-OF-TICKTIME-MILLISECONDS]
, "countdown": [#-OF-COUNTDOWN-TICKS]
, "rounds": [MAX-#-OF-GAME-TICKS]
, "initial_food": [INITIAL-FOOD-COUNT]
, "max_serpents": [MAX-#-OF-SERPENTS]
, "flags": [LIST-OF-FLAGS]
}

[FLAGS] can include walls, random_food and/or increasing_food

Responses

400 Bad Request with a descriptive message
201 Created with

{ "id": [MATCH-ID]
, "rows": [#-OF-ROWS]
, "cols": [#-OF-COLS]
, "ticktime": [#-OF-TICKTIME-MILLISECONDS]
, "countdown": [#-OF-COUNTDOWN-TICKS]
, "rounds": [MAX-#-OF-GAME-TICKS]
, "initial_food": [INITIAL-FOOD-COUNT]
, "max_serpents": [MAX-#-OF-SERPENTS]
, "flags": [LIST-OF-FLAGS]
, "serpents": {}
, "state": "created"
, "cells": [ {"row": [ROW#], "col": [COL#], "content": [CONTENT], "value": [VALUE]}
           , {"row": [ROW#], "col": [COL#], "content": [CONTENT]}
           , …
           ]
}

[CONTENT] can be
- "fruit", in which case [VALUE] will be the amount of food it provides
- "wall", in which case "value" will not be there
[ROW#] and [COL#] are 1-based

`GET /api/games`

Responses

200 OK with

[ { "id": [ID]
  , "rows": [#-OF-ROWS]
  , "cols": [#-OF-COLS]
  , "ticktime": [#-OF-TICKTIME-MILLISECONDS]
  , "countdown": [#-OF-COUNTDOWN-TICKS]
  , "rounds": [MAX-#-OF-GAME-TICKS]
  , "initial_food": [INITIAL-FOOD-COUNT]
  , "flags": [LIST-OF-FLAGS]
  , "max_serpents": [MAX-#-OF-SERPENTS]
  , "serpents": [{…}, {…}]
  , "state": [STATE]
  , "cells": [ {"row": [ROW#], "col": [COL#], "content": [CONTENT], "value": [VALUE]}
             , {"row": [ROW#], "col": [COL#], "content": [CONTENT]}
             , …
             ]
  }
, { … }
]

[STATE] can be "created", "countdown", "started" or "finished"
[CONTENT] can be
- "fruit", in which case [VALUE] will be the amount of food it provides
- "wall", in which case "value" will not be there
[ROW#] and [COL#] are 1-based
Each serpent will look like:

{ "name": [NAME]
, "body": [ [[HEAD-ROW#],[HEAD-COL#]]
          , [[ROW#],[COL#]]
          , [[ROW#],[COL#]]
          , …
          ]
, "status": [STATUS]
}

[STATUS] can be "dead" or "alive"

`GET /api/games/:game_id`

Responses

200 OK with

{ "id": [ID]
, "rows": [#-OF-ROWS]
, "cols": [#-OF-COLS]
, "ticktime": [#-OF-TICKTIME-MILLISECONDS]
, "countdown": [#-OF-COUNTDOWN-TICKS]
, "rounds": [MAX-#-OF-GAME-TICKS]
, "initial_food": [INITIAL-FOOD-COUNT]
, "flags": [LIST-OF-FLAGS]
, "max_serpents": [MAX-#-OF-SERPENTS]
, "serpents": [{…}, {…}]
, "state": [STATE]
, "cells": [ {"row": [ROW#], "col": [COL#], "content": [CONTENT], "value": [VALUE]}
           , {"row": [ROW#], "col": [COL#], "content": [CONTENT]}
           , …
           ]
}

`PUT /api/games/:game_id`

To start a game. The game needs to have at least one player connected, or will return a 403 error.

Parameters

All parameters are required

{"state": "started"}

Responses

400 Bad Request with a descriptive message
403 Forbidden with the text "Forbidden"
200 OK with the same json object as GET /games/:game_id

`DELETE /api/games/:game_id`

To stop a game

Responses

204 No Content

`GET /api/games/:game_id/news`

This endpoint returns a general state of the game as a first event and, if the caller keeps the connection open, it will keep sending new events through it as they happen. This endpoint implements Server Sent Events protocol for that purpose.

Responses

200 OK with content-type: text/event-stream and the body of that response will be a stream of events, with the following format for each event:

event: [EVENT-NAME]
data: [EVENT-DATA]

In that structure:

EVENT-NAME will be a one of the valid Events
EVENT-DATA will be a json structure like the ones you can see in the examples below