GitGame definition - SickTeam/GitGameServer GitHub Wiki

###Creating a Game Create a new game by posting the owner of the repository, the name of the repository, your username and a GitHub access token that can be used to retrieve commits:

POST /games
send:
  {
    owner: "sw701e14",
    repo: "code",
    username: "name",
    token: "abcdefghijlkmnopqrstuvwxyz"
  }
return:
  {
    gameId: "hash",
    userId: "hash2"
  }

The gameId can be used by other players to join the game. In fact, any operation regarding a game requires the gameId in order to identify the game. The userId should be supplied as authentication when sending requests to the server after creating a game.

###Joining a Game A game can be joined by posting a username to a game. To do this the gameId is required. Any operation regarding a game requires the gameId in order to identify the game.

POST /games/{gameId}/players
send:
  { username: "stufkan" }
return:
  { userId: "hash3" }

The userId should be supplied as authentication when sending requests to the server after joining a game.

###Authentication Most requests to a game server requires authentication. To authenticate you must supply your userId in the Authentication header, specifying GH-Token-Auth as the authentication scheme.

Game Settings

The game settings can be modified by posting changes to a setup resource. Below is an example of all the changes that can be applied to a game. Each of these changes is optional.

PUT /games/{gameId}/setup
send:
  {
    contributors: [ { name: "mikaelec", active: true }, ... ],
    excludeMerges: true,
    lowerCase: false
  }

###Game State The state of a game can be retrieved provided you have the gameId. You do not have to be part of a game to retrieve its state - no authentication is required.

The state can only be set by the game creator (requiring authentication) and can only by set to the started state. This can only happen when the game is in the setup state.

GET /games/{gameId}/state
return one of:
  { state: 'setup' }
  { state: 'started' }
  { state: 'finished' }

PUT /games/{gameId}/state
send:
  { state: "started" }

###Guessing

POST /games/{gameId}/rounds/{round}/guesses
send: { guess: "mikaelec" }

Messages

Information about a game, and changes to it, can be retrieved through messages. All game information is retrieved through messages (though state can be retrieved directly).

GET /games/{gameid}/messages
return: { messages: [ ... ] }

The array of messages returned from a message request are listed below. Each message is a json object with three properties; name, resource and timestamp where name identifies the type of the message, resource contains the associated changes to the game and timestamp is the point in time when the message was created. Below is an example of a message:

{ name: 'state', timestamp: "07-09-2015 17:15:02", resource: { state: "started" } }

Supplying the following header in a message request will only return messages created after the listed time.

If-Modified-Since: 07-09-2015 17:15:02

Below are all the supported messages. Only the value object of each messages resource property is listed. For some messages multiple examples are listed.

Name: state

Created when the game state has changed. The resource represents the new game state.

{ state: "setup" }
{ state: "started" }
{ state: "finished" }

Name: setup

Created when the game settings has changed. The resource represents the game settings that have changed. The content of setup message is similar to the requests sent when changing game settings.

{ lowerCase: true }
{ excludeMerges: true }
{
  contributors:
  [
    {
      name: "username",
      active: true
    },
    ...
  ]
}

Name: players

Created when a user joins the game. The resource represents the name of the users that have joined.

{ username: "name1" }

Name: roundstart

Created when a round of the game starts. The resource represents the changes introduced by the commit and which round has started.

{
  linesAdded: 14,
  linesRemoved: 12,
  round: 2
}

Name: roundguess

Created when a user makes a guess in a single round. The resource represents which user guesses and in which round.

{
  username: "name",
  round: 2
}

Name: rounddone

Created when all users have made their guess for a round. The resource represents all information about the round, each guess and the round number.

{
  guesses:
  [
    {
      username: "name1",
      guess: "contributor1"
    }
  ],
  commit:
  {
    contributor: "name",
    message: "blah...",
    linesAdded: 14,
    linesRemoved: 12
  },
  round: 2
}