Post a score

This route can be used to post a score into the leaderboard system and retrieve the local board related to the posted score.

The leaderboard stores only the best score for each player. Therefore if a user posts a score that is less than his best score, the given score will be not persist into the leaderboard. However the returned local board is related to the given score.

Note

This route requires the Digest header key with a specific signature to authenticate and authorize the score post.

POST  /v2/:game/:discr

Header

Key	Value
Content-Type	application/json
Digest	Signed body (see below)

In order to authorize the score insertion, a signature is required. It consists of a body signature with the HMAC-SHA512 algorithm.

Precisely signature = BASE64(HMAC-SHA512(body)) with the game token as the secret key of HMAC-SHA512.

See with the admin for game token issues.

Route parameters

Key	Description
`:game`	the game name
`:discr`	the major discriminant (a discriminant is a criteria that identify the board where the score has to be put. Note that a game can have several independent leaderboard which are identified by a distinct discriminant)

Query parameters

Query parameters are optional and are useful to filter the local board related to the posted score.

Field	Default	Remarks
`number_of_results`	10	By default: 5 scores before the posted score, the posted score and the 4 following scores
`platform`	n/a	Required if `session` or `user` are provided
`session`	n/a
`discr`	n/a	An array of additional discriminants which are cumulative
`launcher`	n/a	An array of launcher names which are not cumulative
`country`	n/a
`extra`	0	If 1 extra fields are returned
`stats`	0	If 1 stats fields are returned

Request body

The request body must be send with the application/json format.

Field	Required	Remarks
`score`	Yes	An integer value
`platform`	Yes
`user`	Yes
`pseudo`	Yes
`session`	Yes
`extra`	No	Plain text that can store metadata
`discr`	No	An array of additional discriminants which are cumulative
`launcher`	No	The launcher name
`country`	No
`stats`	No	A json object with no depth

Response

Code	Remarks
200	The score has been posted and the local board have been returned with success
400	There are unexpected field that have been sent, missing required field or invalid signature (see error message)
401	Authentication failed
500	Internal error

The response is sent in the JSON format.

{
    "rank": 35,
    "ranking": [{ ... }, { ... }, {
        "rank": 35,
        "platform": "octopod",
        "session": "a",
        "user": "b",
        "pseudo": "c",
        "score": 42,
        "created_at": "2020/12/01 10:09:08",
        "extra": "<data of format texte ou binaire retourné via un Base64>",
        "discr": ["time:10mn", "difficulty:hard"],
        "launcher": "wanadev2",
        "stats": {"foo": "bar"}
        }, { ... }, { ... }, ...]
}

Note that:

launcher field is returned only if a launcher was specified in the request body
extra field is returned only if extra query parameter is equal to 1
stats field is returned only if stats query parameter is equal to 1
the number of results depends on the number_of_results query parameters (10 by default)
the posted score is always centered in its local board
if the given score is not the best score of the player, it will not persist into the leaderboard but the returned local board is related to this given score