HTTP.md

RESTful API for Serpents

Endpoints

POST /api/games/:game_id/serpents

To create a serpent (i.e. join a game)

Parameters

All parameters are required

{"name": [SERPENT-NAME]}

Responses

• 404 Not Found if the game was not found
• 400 Bad Request with a descriptive message
• 201 Created with

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

• [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
• [DIRECTION] can be "up", "down", "left" or "right"
• [TOKEN] is unique per serpent, do not share it

---

PUT /api/games/:game_id/serpents/:token

To change the direction of the serpent

Parameters

All parameters are required

{"direction": [DIRECTION]}

Responses

• 404 Not Found if the game was not found
• 400 Bad Request with a descriptive message
• 403 Forbidden with the text "Forbidden"
• 200 OK with the same json object as POST /games/:game_id/serpents

---

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

Events

The currently supported events are:

game_status

The event data is a json representation of a game (see below)

serpent_added

The event data is a json representation of a serpent (see below)

game_countdown

The event data is a json representation of a game (see below)

game_started

The event data is a json representation of a game (see below)

game_updated

The event data is a json representation of a game (see below)

collision_detected

The event data is a json representation of a serpent (see below)

game_finished

The event data is a json representation of a game (see below)

Objects

Game

{ "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
• [FLAGS] can include walls, random_food and/or increasing_food

Serpent

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

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