Room requests

In all requests {game} refers to the appropriate game name.

In order to start a session, users may join or create a room. The host of the room may start a session if all the users in the room are ready, and the number of players in the room fulfils any requirements of the game.

Create a room

Request:

POST games/{game}/rooms

Request body:

{
    "name" : "30m no rush",
    "password" : "30m no rush",
    "options" : { ... }
}

password and options are optional.

Response:

201 Created with Location: games/{game}/rooms/{room-id}. You will automatically join the created room, and be set as the host.

{
    "name" : "room name",
    "game" : "game name",
    "users" : [ ... ],
    "options" : { ... }
}

Join a room

Request:

POST games/{game}/rooms/{room-id}/join

Request body (optional):

{
    "password" : "hunter2"
}

Response:

200 OK if you joined successfully or were already in the room. The response body will contain the id of the room.

{
    "id" : 1,
    "game" : "noughts",
    "type" : "room"
}

404 Not Found if the room requested doesn't exist.

410 Gone if the room requested no longer exists.

400 Bad Request with corresponding error codes if:

• The room is private and you supplied an incorrect password (room.incorrect_password)
• The room is full (room.room_full)

Leave a room

Request:

POST games/{game}/rooms/{room-id}/leave

Response:

204 No Content if you left successfully.

400 Bad Request if you were not in the room.

Update room options

Update the room's options. You must be the host to do this. A room's options consist of an arbitrary JSON object whose meaning it is up to the game itself to interpret.

Request:

PUT games/{game}/rooms/{room-id}/options

Request body:

{
    ...
}

Response:

204 No Content if the room's options were successfully updated.

Kick user

If you are the host, you can kick a user from a room.

Request:

POST games/{game}/rooms/{room-id}/kick

Request body:

{
    "user_id" : 3
}

Response:

204 No Content if you kicked the user successfully.

Get a list of rooms

Request:

GET games/{game}/rooms?limit={limit}&offset={offset}

• {limit} The maximum number of rooms to show. Optional; default is 10.
• {offset} The number of rooms to skip from the start. Optional; default is 0.

Response:

[
    {
        "roomId" : 0,
        "name" : "room name",
        "game" : "game name",
        "numUsers" : 1,
        "maxUsers" : 4,
        "active": true,
        "private": false,
        "options": { ... },
        "host": {
            "userId": 1,
            "username": "Mickey Mouse"
        },
        "userInRoom": true
    },
    ...
]

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).

There is also an extra key-value pair userInRoom which is true if the requesting user is in the room. This value is only present in this request, not in the

Note that this response does not return the list of users inside each room. You must make a request for a single room (below) if this is required.

Get a room

Request:

GET games/{game}/rooms/{room-id}

Response:

{
    "roomId" : 0,
    "name" : "room name",
    "game" : "game name",
    "numUsers" : 1,
    "maxUsers" : 4,
    "active": true,
    "private": false,
    "options": { ... },
    "host": {
        "userId": 1,
        "username": "Mickey Mouse"
    },
    "users": [
        { "user": { "userId": 1, "username": "Mickey Mouse" }, "isHost": true },
        { "user": { "userId": 2, "username": "Donald Duck" }, "isHost": false },
        ...
    ]
}

Note that this response also returns the list of users inside the room.

Start a session

Starts a session with the users of this room. Only the host may make this request.

Request:

POST games/{game}/rooms/{room-id}/start

Response:

201 Created with Location: games/{game}/sessions/{session-id}.

Events

Request:

GET games/{game}/rooms/{room-id}/events?after-event-id={after}
GET games/{game}/rooms/events?after-event-id={after}

The URL without the room id is used to subscribe to events for all rooms.

Response:

[
    {
        "id" : 0,
        "event" : {
            "type" : "new_room",
            "roomId" : "1",
            ...
        }
    },
    ....
]

For more information about events, see events.

Room event objects will have at least a type field and a roomId field. There may be additional values depending on the event:

room_created

Sent when a new room is created.

Additional values:

• room See above for structure of room object - users not included

room_gone

Sent when a room is closed. This happens if either the host leaves it, or if the users start playing a game.

Additional values:

• roomId The id of the closed room
• sessionId (Optional) The id of the session the users started playing

user_join

Sent when a user joins a room.

Additional values:

• roomId The id of the closed room
• user ({"user":{"userId":5,"username":"test_user"},"isHost":false}) See above for more details about structure of user in room object
• numUsers The number of users now in the room
• maxUsers The maximum number of users the room can hold

user_leave

Sent when a user leaves a room or is kicked.

Additional values:

• roomId The id of the closed room
• userId The is of the user who left the room
• numUsers The number of users now in the room
• maxUsers The maximum number of users the room can hold