RFC: Club Data

This Request For Comments covers four new endpoints to describe a Club and its membership.

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

/pub/club/{url}

This is the data representation of the club itself. The data response will include:

• "@id" : based on the url
• "name"
• "club_id" : the internally-used, never-changing numeric ID
• "country" : URL to the country endpoint the Club identifies itself as part of
  "location" (may be null)
• "created" : timestamp of the time created
• "last_activity" : timestamp of the time of the last news, forum, or other activity (used to see if there is "new" content)
• "admin" : array of player profile URLs for admins and super-admins of this club
• "visibility" : either "private" or "public", based on if the Club is private
• "join_request" : URL to request joining the club
• "icon" : the group image (may be null)
• "description" : full text description (may be empty string, and may be quite long)

/pub/country/{XX}/clubs

An array of club endpoint URLs per country. Updated once per day, like other country endpoints.

/pub/club/{url}/members

An array of player profile endpoint URLs per club. Updated once per day, like the country endpoints.

/pub/player/{username}/clubs

An array of club endpoint URLs per player. Updated once per day, like the country endpoints.

Club stats and games will be described in future RFCs.

I don't know how many clubs there are, but am slightly wary about the larger clubs. How large is the resulting data going to be for "Dan Heisman Learning Center" (13,000+ members) which is one of the larger groups I know of off hand?

Per-user club lists are unlikely to be a problem in comparison: I know of users who collect clubs and have topped 600, but that's 20x less than the members in DHLC!

I also note (and the documentation will need to) that some of those arrays will be empty; there are clubs with no current admins.

Related: in V3 depending on the view and I've not nailed it down but will if necessary, sometimes closed accounts are shown as admins and sometimes they are not. Personally I've found this useful only for tracking "retread" users, but I mention it for completeness.

On the main club page, no closed accounts are listed.  On the members page, in the sidebar, the closed accounts of former admins are listed.

I believe this is unintentional and probably a bug, but I occasionally find it useful from a cheater-detection perspective, so I kind of hope it doesn't go away.

The obvious endpoints that might return large data are /pub/country/{XX}/clubs  and /pub/club/{url}/members

 I think we should have the ability to get the whole data set, but perhaps some filtering might be helpful in addition. For example:

/pub/club/{url}/members/active

/pub/club/{url}/members/joined/{YYYY}/[{MM}

Is the date a member joined a club going to be useful information? We do not have plans for including that anywhere, as yet.

We are probably changing these lists of URLs to be lists of usernames, instead. This inhibits some automatic crosslinking that we liked, but gives us a 75% reduction in storage size. (The download size is less of a concern; once we get proper gzip compression over HTTP, the URLs and usernames are about the same to download.)

With this change, even the Chess University club with 48,000 members would have something like an 800Kb download.

The date a member joined is helpful for judging if they are active.

In one club I'm SA of a new member joined over a week ago, but we're yet to open a match where he would be eligible to play.

Players that have been members for four years and never played a match ... different story. We call them "dead wood" and some admins like to keep them (numbers) and some like to get rid of them (to be able to work out what matches our players might be able to play in).

I agree with skelos but his example is at the extreme/obvious end. I've mentioned it elsewhere but I'm sure most club adin's would like to see 2-3 additional member sorting options. Date last played for club and number of times are two that come quickly to mind.

End cases are a bane for computer programmers, so I always look for them!

"What do you need?"

<answer follows>

"Right, sounds doable. Any exceptions to that?"

"Oh, no."

"No alternatives for particular tests or doctors?"

"Well, yeah, Dr. X we have to work for differently, becuase"

Me (silently): Gotcha!

Number of times might (or might not, brainstorming here) be better provided as a list of matches (or live tournaments?) participated in. Then you can simply count them, or examine them.

Where the data volume allows, I'd rather get the data and have to do a little more processing locally than not be able to access the data.

I do not think it would have too much of a bad affect if the endpoint returned the plain old usernames :-)

I'll re-enter this discussion after the antibiotics kick in. ATM, my brain's working about as well as the wife's. I may finish up sending skelos a PM with my thoughts and ask him to translate them.

Heh, OK, Theo.

Get better soon!

Date of joining club is very very useful for admins.

Yes. An activity report I'm writing would like to know when a member joined. If they joined recently, they might not have had any chance to join a match.

Obviously this comment would have been useful much sooner. Sorry 'bout that.

Edit: I more or less did make that comment earlier. I wish my memory worked like it did 25 years ago.

Can we split admins into admins and super-admins, please? That is visible on the website and not via the endpoint.

I'm not sure if exposing the "owner" of the club is useful and it isn't visible on the website. (When quitting a club and discovering that I was the owner it was a nuisance, in fact.)

I'd like to reiterate this request, please. I want the data in some code I'm writing today, and it's simply not possible to get without scraping the website.

It's not critical as for my use it can be worked around manually, but it would be very nice to have, hence my repeating the request.

Think of it as going from theory "I think I want this" to practice "Damn, I can't get this? #$@()*)" rather than nagging, please.  But do add it?

Thanks for your (re-)consideration.