Minor documentation errata

Hi,

If tradition holds, I'll find a few things as I work through the documentation. If someone either is prepared to check "follow" on this thread or ask me to post a note wth the thread URL when I update it, that would be good.

I'll try to keep things to one item per post so they can be checked off somewhere ("user error", "fixed", "will fix", ...)

Giles

Excellent idea! Following...

Except I don't seem to have posted whatever it was I'd noticed at the time. Oh well. It was a reference in a comment to "player" somewhere in a club related endpoint. I'll trip over it again.

Real nitpick. From https://www.chess.com/news/view/published-data-api#pubapi-endpoint-match-profile I assume autostart will be "true" or "false", even in registration phase?

"autostart":false

https://www.chess.com/news/view/published-data-api#pubapi-endpoint-match-profile

"rules" appears twice within "settings:

    "settings":{  
      "rules":"chess",
      "time_class": "string", // time-per-move grouping, used for ratings
      "time_control": string, // time control
      "rules": string, // game variant information (e.g., "chess960")

https://www.chess.com/news/view/published-data-api#pubapi-endpoint-match-profile

Does not document the 'stats' link for the player.

In the match endpoint RFC there is a suggestion that stats are included because you do not keep snapshots of that data, however you could document that and the 'stats' URL is not hard to construct. It being present doesn't seem to hurt much, but the critical points of rating and timeout_percentage are brought up, so I would drop stats. It's easy enough to put together from  the username.

teams": [
        "team1": {

I think this should be:

"teams": {
        "team1": {

i.e. "teams" is an associative array (sorry I don't know the JSON jargon; I should learn it) and not a list.

@skelos thank you for your proofreading, I've corrected all the typos and mistakes you have found.

Thanks. Not really proof reading just what I noticed as I was working with the endpoint earlier. Back to it now.

And ... here comes more. Nothing to panic about; minor stuff but inconsistent.

URL pattern: https://api.chess.com/pub/match/{ID} 
Data format of match in its registration phase:

...

                    "played_as_white": "string", //result {win, lose, resign, etc.} of player when played as white (if game's finished)
                    "played_as_black": "string", //result {win, lose, resign, etc.} of player when played as black (if game's finished)

Cannot apply in registration state, and is not appearing for "in_progress" and is not documented for "in_progress" or "finished".

Cut from the "in_progress" documentation and don't worry about it? Going to the board shouldn't be too much if more than the team scores are wanted?

"in_progress" (and probably "finished") matches are having timeout_percentage shown but it isn't documented. It's important during registration (some teams/competitions allow players to be removed) but afterward? Harmless but not necessary unless someone has a use case I haven't thought of? (Maybe history: if they time out in this match, knowing what the timeout percentage was for the previous 90 days might be useful. But is it percentage at match start, or current percentage? If current I see no point, although again someone else may.)

https://www.chess.com/news/view/published-data-api#pubapi-endpoint-match-profile

For finished matches, there is no documentation of end_time yet it is supplied. As I like having it, please include it in the documentation rather than removing it from the data!

The per-player games endpoint is I think incorrectly documented.

The documentation says:

https://www.chess.com/news/view/published-data-api#pubapi-endpoint-games-current

{
  "white": "string", // URL of the white player's profile
  ...
}

The actual provided data appears to be more like:

{ "games": [
   { "url": ...
      ...
   }
   ...
   ]
}

The title "Data Format, each Game:" was supposed to show only the information of one game inside the games property which is written above. I will rephrase to make it more clear.

Thanks Andrea. I worked it out afterwards, but most/all of the other documentation would show the "games" entry, and when using the documentation as a reminder rather than first-time learning, it is formatted blocks my eye at least is drawn to.

That said, it's minor. The bugs I reported yesterday/last night are much less so.

https://www.chess.com/news/view/published-data-api#pubapi-endpoint-games-archive

"eco" appears twice and the format is a bit scrambled:

  "end_time": 1254670734, // timestamp of the game end
  "time_control": "string", // PGN-compliant time control
            "eco": "string", //URL pointing to ECO opening (if available),
          "tournament": "string", //URL pointing to tournament (if available), 
  ing", // time-per-move grouping, used for ratings
  "rules": "string", // game variant information (e.g., "chess960")
  "eco": "string", //URL pointing to ECO opening (if available),

https://www.chess.com/news/view/published-data-api#pubapi-endpoint-match-profile

Timeout went in and rating was pulled out at least once matches are in_progress or finished. I found discussion here (in the RFC) and notes about breaking changes, but the original documentation is now a bit misleading I think:

    "teams": {
        "team1": {
            "@id": "URL", // API URL for the club profile
            "name": "string", // club name
            "score": score,
            "players": [
                {
                    "username": "username", 
                    "board": "url", // url of board
                    "rating": 1355, //rating of player Only during registration?
                    "timeout_percent": 25, //timeout percentage
                    "status": "basic" //status of user
                }
            ]
        },

what are all the possible values for played_as_black / white? 

@edpratomo I've added a section here

https://www.chess.com/news/view/published-data-api#pubapi-endpoint-player-stats

    "timeout_percent": 9 // integer percentage of games lost by timeout

Is this over the last 90 days like the website?

I would prefer that whatever we get here be the same as what is presented on the website. If that means "for the last 90 days" and that's what is delivered, could that be noted please?

If there is a difference, it is going to matter to a few rules-lawyer types, and I'm also curious that this is an integer and the website gives two decimal places. Hardly the end of the world, but 14.99% is not 15% ... to some of those rules lawyers.