Game Server documentation

Introduction

All URLs are taken to be relative to the application root.

For example, https://xikka.com:8759/.

The game server fulfils two main roles - managing user accounts (including chat, friends, inviting players to a game, creating accounts) and acting as a server for specific games.

Communication

The server uses REST for all communications. That means requests are made via HTTP with verbs suitable to the task at hand (in general, GET for fetching a resource, POST for creating, PUT for updating, DELETE for deleting). Successful responses will have response codes in the 1xx-3xx range. Otherwise, 4xx-5xx means there was an error. See HTTP Status codes for more information.

In the case of 4xx, the response body will contain a description of the error in the form:

{
    "error" : "login.incorrect_credentials",
    "description" : "The username or password you provided was incorrect."
}

The error uniquely identifies the error type (and the descriptions map 1-1 to the errors). The descriptions are always in English and are provided so they can be read for debug purposes (curl etc.). They shouldn't be presented to the user, who should see a localised string based on the error code.

JSON is used for all communications.

The responses will be one of the following:

Authentication

Requests will often require authentication of some kind. For documentation pages, authentication must be basic and you must be an admin user. For login/registration requests, no authentication is required. For all other requests, authentication must be bearer, using a token acquired by the login request (that is, the request must contain a header of the form: Authorization: Bearer OLk/nSUoGLj+2Y).

Should this not be observed, the client should expect a 401 Unauthorized. This is distinct from 403 Forbidden which means the client has provided credentials, but they are not valid.

A token may expire after some time. If this happens, the client should request a new token.

Security

All requests must be made over https. The certificate is currently a self-signed one so clients should include a truststore (which can be exported from firefox) to verify the validity of the server until a trusted certificate is purchased. (Todo: is it worth it to buy one?)

Database

All state is stored in the database in order to ensure that server downtime will not majorly disrupt ongoing sessions. It is vital that games added to Kangaroo do not store any state in their class which cannot be re-created.

Naming convention

Keys inside JSON objects use camelCase. Codes (such as error codes or event codes) use underscore_separated_names.