RFC: Tournament data

This Request For Comments covers a new set of endpoints to provide information about tournaments, tournaments' rounds and participants.

Tournaments will be referenced by their "url" value, which is the unique string used for their URL on the website.

/pub/tournament/{url}

This endpoint should provide all relevant information related to a specific tournament rules and stats: 

{
    "name": name,
    "url": url of tournament,
    "description": description of tournament, 
    "creator": url to creator,
    "type": game type, 
    "status": status, // {finished, closed, in progress, registration}
    "start_time": timestamp, 
    "finish_time": timestamp, 
    "current_round": url to current round , //null if tournament is terminated 
    "rules": {
        "time_control": string, //time control as defined in PGNs   
        "is_rated": bool,
        "is_official": bool, 
        "is_invite_only": bool,
        "min_rating": integer,
        "max_rating": integer,
        "initial_setup": string //if not standard,  
        "initial_group_size": integer,
        "user_advance_count": integer,
        "max_concurrent_games": integer,
        "use_tiebreak": bool,
        "premium_only": bool,
        "allow_vacation": bool,
        "winner_places": integer, 
        "group_size": integer,
        "registered_user_count": integer, 
        "games_per_opponent": integer, 
        "total_rounds": integer, 
        "concurrent_games_per_opponent": integer,
    },
    "players": {
        [ 
            "user1",
            "user2",
            //list of player’s usernames
        ]
    },
    "rounds": {
        [ 
            "/pub/tournament/{url}/1", 
            "/pub/tournament/{url}/2",
            //list of turns urls
        ]
    }
}

Updates: when a tournament status changes or a tournament's round ends

/pub/tournament/{url}/{round}

This endpoint should provide all relevant information related to a specific round stats:  

{
    "groups": {
        [ 
            "/pub/tournament/{url}/1", 
            "/pub/tournament/{url}/2"
            //list of groups urls
        ]
    }
}

Updates: when a tournament's round ends

/pub/tournament/{url}/{round}/{group}

This endpoint should provide all relevant information related to a specific round's group stats:  

{
    "games": {
        [ //list of games
            {
                "white": { // details of the white-piece player:
                    "username": "string", // the username
                    "rating": integer, // the player's rating at the start of the game
                    "result": "string", // the player's result, if game's finished
                    "@id": "string", // URL of this player's profile
                 },
                 "black": { // details of the black-piece player:
                     "username": "string", // the username
                     "rating": integer, // the player's rating at the start of the game
                     "result": "string", // the player's result, if game's finished
                     "@id": "string", // URL of this player's profile
                 },
                 "url": "string", // URL of this game
                 "fen": "string", // current FEN
                 "pgn": "string", // final PGN, if game's finished
                 "start_time": timestamp, // timestamp of the game start (Daily Chess only)
                 "end_time": timestamp, // timestamp of the game end, if game's finished
                 "time_control": "string", // PGN-compliant time control
                 "time_class": "string", // time-per-move grouping, used for ratings
                 "rules": "string" // game variant information (e.g., "chess960")
             }
         ]
     }
}

Updates: when a game updates

/pub/player/{username}/tournaments

 This endpoint should provide all relevant information related to which tournaments a player has attended:

{
    {
    tournaments: {
        [
            {
                "url": url, //url to tournament
                "wins": integer, //number of wins
                "losses": integer, //number of losses
                "draws": integer, //number of draws
                "points_awarded": integer, //points awrded
                "status": string // {winner, active, registered, invited, eliminated, withdrew, removed}
                "placement": integer, // final placement if tournament is finished
                "total_players": integer, //total players in tournament
            }
        ]
    }
}   
}

Updates: when a tournament status changes

Does this endpoint get you what's needed for your? Are there related data we missed that are essential? If possible, please include specific examples of how you intend to use the data, especially if you request that we change this output in some way.

At a quick read through it looks good. Pleased to see "withdrew" in there; TDs don't like players who withdraw. (Although I have, and others have: better to withdraw than timeout if Real Life is sucking time.)

Breaking change: please note that we have decided to redesign the Tournaments endpoints in order to not duplicate data or have to invalidate cache too often. 

The "rounds" endpoint will show only the list of groups related to that round, and every group will show the list of games. The player's list of a group can be inferred by getting player's info of each game.

The final draft of tournament's endpoints has been added in documentation. Feel free to continue use this thread for any new idea or suggestion (or bugs, of course!).

As far as I can tell, the only way to reach a Tournament's url-ID is through an individual player's data.  Any chance we'll see a public endpoint with a site-wide list of URL-ID for past/present/future tournaments? 

Thank you in advance for your response.