All sessions requests include the corresponding game in the URL.
This will return a list of the sessions you are in, matching any filters you provide.
A brief description of all the fields: - sessionId - the id of the session, should be included in the url for requests pertaining to this session - game - the game for which this session corresponds - active - true if the game is still in progress, false otherwise - players - an array of all the players in the game
Players consists of the following fields: - user - the username/userId of the user controlling the player - isHost - whether this player is the host of the session (the one who created the session) - isCurrent - whether this player is a current player, meaning they may make a move (it is their "turn")
It is up to the client to work out which sessions currently need input from the user.
Session environment is not included in this response.
Request:
GET games/{game}/sessions?active={active}&limit={limit}&offset={offset}
GET parameters:
- `{active}` - if `true`/`false`, will only fetch sessions which are/aren't active (currently being played). If omitted, all sessions will be returned.
- `{limit}` - the maximum number of sessions to return, default 20
- `{offset}` - the number of sessions to skip from the start of the list, default 0
Response:
[
{
"sessionId" : "1",
"game" : "noughts",
"active" : true,
"players" : [
{"user": {"userId": 1, "username": "ezekial"}, "isHost": true, "isCurrent": false, "playerId": 0},
...
]
},
...
]
In addition, the header will contain an X-Total-Results value which indicates the total number of session which matched the filters (as opposed
to the number of sessions in the response, which is limited by limit).
Request:
POST games/{game}/sessions/{session-id}/turn
The request body should be a valid json object. The exact details of this object are specified by the game.
Response:
204 No Content if the turn was a success.
Note that session environment is included in this response. The exact details of this object is specified by the game.
Additionally, there is the toEventId field which is the id of the last event to be fired when this environment was created. Thus, the client is expected to listen for events which occur after this (since this event and before should have been encorperated into the environment).
Note that the environment which is returned from the request is not necessarily the "entire" game state as stored by the server. Games are able to hide certain bits of information from the client as appropriate in order that one client can't see information they should not be privvy to (for example, the cards in an opponent's hand). What exactly, if anything, is redacted is specified by the game.
Request:
GET games/{game}/sessions/{session-id}
Response:
{
"sessionId" : "1",
"game" : "noughts",
"active" : true,
"players" : [
{"user": {"userId": 1, "username": "ezekial"}, "isHost": true, "isCurrent": false, "playerId": 0},
...
],
"environment" : {
...
},
"toEventId" : "1"
}
Request:
GET games/{game}/sessions/{session-id}/events?after-event-id={after}
Response:
[
{
"id" : 0,
"event" : { ... }
},
....
]
For more information about events, see events.
The game event object is often defined by the game, but there are some events which are not.
Not all players receive all events - it is up to the game who receives what events.
The event object refers to the JSON objects returned from this request in the list -- includes the id and a game event object. The game event object refers to the arbitrary JSON object within the event object.
A game event object may contain a key called "_type". If it does, it's an event fired by the server (not defined by the game). These events should be treated specially, and are detailed below.
If embedding in the web, these server events should be passed to the handleServerEvent function. This is not required as some games may wish to handle the events themselves.
Game event objects which contain a "_type" key are server events. Here they are:
{
"_type" : "over",
"scores" : {
"1" : 0
"0" : 1
}
}
The "over" event contains a score map which tells the score for each player in the session, by player id. A higher score is always better (but it's up to the client how to, or indeed whether to, display the score). In the above example, player 0 won the session!
{
"_type" : "log",
"message" : "Message to display to user in the log"
}