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
------
.. list-table::
   :widths: 25 75
   :header-rows: 1

   * - 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
----------------

.. list-table::
   :widths: 25 75
   :header-rows: 1

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

.. list-table::
   :widths: 20 20 60
   :header-rows: 1

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

.. list-table::
   :widths: 20 10 70
   :header-rows: 1

   * - 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
--------

.. list-table::
   :widths: 20 80
   :header-rows: 1

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

.. code:: json

    {
        "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