Query re website URL in endpoints

Hi,

This is not specific to a single endpoint so I am starting a new thread.

The match endpoint (today I am interested in matches in "registered" state, to see how balanced they are) is going I believe to give me all I need. For reference to save people who haven't memorised the whole API from hopping about too much, I start here:

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

with

    "registered": [
        /** List of matches */
        {
            "name": "match name", //the team match name
            "@id": "URL", // URL pointing to the team match endpoint
            "opponent": "https://api.chess-dev.com/pub/club/testing-teams", // URL pointing to the opponent club endpoint
        }
    ]

Along the way, however, I noticed this inconsistency. For the team match endpoint

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

the first two documented items of data are very useful information:

    "name": string, 
    "url": "URL", // the URL of the match on the website

I can see using the name and URL in any human viewable output.

Then I moved to the opponent:

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

  "name": "string", // the human-readable name of this club

Nice. But the only URL I get is @id:

  "@id": "URL", // the location of this profile (always self-referencing)

If it is always OK simply to substitute "https://www.chess.com" for "https://api.chess.com/pub" in this instance so that

https://api.chess.com/pub/club/asger-s-great-viking-warriors

becomes

https://www.chess.com/club/asger-s-great-viking-warriors

all is well. In that case, however, why provide "url" in the team match endpoint but not in the club profile endpoint?

Granted this is a small point, but either the url is extra work on your side that might one day prove restrictive and might as a "Breaking Change" go away, or if it's so stable and desirable enough might it be propagated to more endpoints?

I note in passing that working from @id is going to be much more reliable than working from "name" as the conversion from human readable club names to as-used on the webite process is lossy. A couple of examples:

"Asger's Great Viking Warriors" → asger-s-great-viking-warriors

"France/Deutschland Group" → francedeutschland-group

"A.R.C." → a-r-c

The forward slash is lost in the second example, and the first and third show three different characters (apostrophe, space and period) all being converted to a hypen. Plus there is the case folding.

This isn't a bug report, but I suppose it's an enhancement request. I can see (from my own development days) taking the request "make it consistent" and removing "url" from endpoints where a translation of @id will work, or alternatively providing "url" almost anywhere it is reasonable.

The former is probably less work, and the latter better insulates users of api.chess.com from changes in namespace rules on the website that aren't mapped identically to changes in endpoints.

Anyway, having fun, and now having been distracted and written this up I'll go back to what I was doing, which was actually using the endpoints.

Thanks,

Giles

All of these endpoints ought to have similar info, and we are reviewing what we have to standardize some of these now. This is what I'd expect:

• "name" if the item has a human-readable name entered by the creator
• "url" is a link to the website representation of this item (the club home page, or the team match overview, etc)
• "@id" is the URL of the data that you have retrieved, so the for the data at https://api.chess.com/pub/club/chess-com-developer-community the "@id" value is "https://api.chess.com/pub/club/chess-com-developer-community"

It looks like "@id" is missing from the team match profile, and the "url" is missing from the documentation (but not the data) for the club profiles.

Thanks @bcurtis. name (where appropriate), url and @id are all useful, and I do like consistency although I know it's a bugbear to keep going back to "completed" endpoints as something changes across the whole API.

FYI, I am now at the point where I have an admin (whom I doubt is a programmer) asking for a couple of my utilities. So I shall have to get around to finding out if my scripts run on Windows (I'm using perl; they clearly can, but if "out of the box" Activestate perl is not enough I'll have to review.)

I may also or instead host some items on a website, but for some tools I think the command line will do, even on Windows. I shall see what feedback I get about that. The biggest advantage of not using a website is that anyone who has the tools can tweak them (or have someone else tweak them) and not be dependent upon me.

I like being useful; I dislike being irreplaceable. Nobody is irreplaceable when it comes down to cases. (But I'm glad when my doctor said last year "You might have had a heart attack" it turned out a few stressful weeks later that I hadn't. Happy about that.)