Back end Standings API

Introduction

This page presents the API presented by the backend for the standings.

By standings, we mean:

• Standings for a given game.
• Global standings.

Retrieve Problem Standings

Standings for a problem can be ordered in multiple ways:

• By the number of submissions.
• By the score.
• Increasing / decreasing.

People that show up the the problem standings are people who made at least one submission for the given problem.

• Permissions required: None
• Address: /api/Standings/GameStandings
• Request JSON:

    {
        "requested_entries": "Number of requested standings entries",
        "requested_entries": 10,
        "requested_offset": "Number of entries to skip (for pagination)",
        "requested_offset": 0,
        "GameID": "id of the game we want to get standings to",

        "order_by": "By default is 'score'. Option: 'score' / 'submissions'",
        "result_order": "'increasing' or 'decreasing'. By default 'decreasing'",
    }

• Response JSON:

    {
        "entries_returned": "Number of returned games",
        "entries_returned": 10,
        "entries_found": "number of found entries",
        "entries_found": 314,

        "entries": "List of the entries, in order",
        "entries": [{
            "best_sumission_id": "id of the user's best submission",
            "submissions": "number of submissions",
            "submissions": 2,
            "Points": "score of the player",
            "Points": 100.3,
            "AuthorID": "id of user who got this place in the standings",
            "AuthorUsername": "username of the author",
        }],
    }

Retrieve Global Standings

Global standings can be ordered by:

• By the number of submissions.
• By the total score.
• By the number of defeated bots. (not yet implemented)
• Increasing / decreasing.

API of the global standings:

• Permissions required: None
• Address: /api/Standings/Global
• Request JSON:

    {
        "requested_entries": "Number of requested standings entries",
        "requested_entries": 10,
        "requested_offset": "Number of entries to skip (for pagination)",
        "requested_offset": 0,

        "order_by": "By default is 'score'. Option: 'score' / 'submissions' / 'defeated'",
        "result_order": "'increasing' or 'decreasing'. By default 'decreasing'",
    }

• Response JSON:

    {
        "entries_returned": "Number of returned games",
        "entries_returned": 10,
        "entries_found": "number of found entries",
        "entries_found": 314,

        "entries": "List of the entries, in order",
        "entries": [{
            "submissions": "number of submissions",
            "submissions": 2,
            "TotalBotsBeaten": "number of defeated bots (not yet implemented)",
            "TotalBotsBeaten": 34,
            "TotalPoints": "score of the player",
            "TotalPoints": 123.45,
            "AuthorID": "id of user who got this place in the standings",
            "AuthorUsername": "username of the author",
        }],
    }

Retrieve User's Standings For A Game

• Permissions required: None
• Address: /api/Standings/UserStatsGame
• Request JSON:

    {
        "GameID": "game we request info for",
        "UserID": "id of the user",
    }

• Response JSON:

    {
        "error_message": "Reason why the action failed. Doesn't exist if successful",
        "status": "'ok' if successful, 'fail' if not",

        "has_submissions": "true if the user has at least one submission",
        "has_submissions": true,
        
        "submissions_count": "number of submissions made by the user",
        "submissions_count": 10,
        
        "rank": "position of the user in the game ranking",
        "rank": 4,

        "best_submission_id":  "Id of the best submission",

        "submissionIDs": ["ids of the submissions"],
    }

NOTE: if the user didn't submit anything to the game, then submissions_count, rank, best_sumission_id and submissionIDs won't exist.

Retrieve User's Global Standings

• Permissions required: None
• Address: /api/Standings/UserStatsGlobal
• Request JSON:

    {
        "UserID": "id of the user we want to check",
    }

• Response JSON:

    {
        "submissions": "number of submissions",
        "submissions": 2,
        "TotalBotsBeaten": "number of defeated bots (not yet implemented)",
        "TotalBotsBeaten": 34,
        "TotalPoints": "score of the player",
        "TotalPoints": 123.45,
        "rank": "rank of the user, based on the score",
    }