Get leaderboard
===============

This route can be used to retrieve the global leaderboard with optional filters.

::

    GET  /v2/:game/:discr

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 global leaderboard.

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

   * - Field
     - Default
     - Remarks
   * - ``offset``
     - 0
     - 
   * - ``limit``
     - 50
     - 
   * - ``platform``
     - n/a
     - Required if ``session`` or ``user`` are provided
   * - ``session``
     - n/a
     - 
   * - ``user``
     - 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

Response
--------

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

   * - Code
     - Remarks
   * - 200
     - The global leaderboard have been returned with success
   * - 400
     - ``(game/discr)`` does not exist or unexpected query parameters or missing required parameters (see error message)
   * - 500
     - Internal error

The response is sent in the `JSON` format.

.. code:: json

    [   
        { ... }, { ... }, 
        {
            "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:

* ``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 ``limit`` query parameters (50 by default)
* the board starts with the rank ``offset`` + 1 (starts with the 1st by default)
* if there is no entry for the requested leaderboard, an empty array is returned