Feature Request: Add user's latest rank to GET /api/archives/:user

[Ellyster]

It will be great if GET /api/archives/:user include more information about the KGS user, for example their current rank.

Instead of needing to do GET /api/archives/:user, then GET prev, and then go to content -> games -> first game -> white (and black) and finally check players' names and ranks, for an action so common as querying for an user latest rank in KGS.

http://www.lifein19x19.com/forum/viewtopic.php?p=173827#p173827

[anazawa]

Thanks for your request. I have 3 ideas of how to add your feature:

A) Add HTTP method to MetaKGS.org (your idea). For example, we can add "GET /api/users/:user" which includes the user's latest rank, the number of games and so on:

{
    "name": "foo",
    "rank": "1d",
    "games": 123,
    "archives_url": "http://metakgs.org/api/archives/foo",
    ...
}

B) Write a MetaKGS client using your favorite language and then implement the object method #get_latest_rank_by_name (my recommendation). You have already understood how to get the user's latest rank using MetaKGS APIs, and so it will be easy for you. I can also introduce your client on MetaKGS.org.

C) If you are a Perl user, you can subclass WWW::GoKGS::Scraper::GameArchives to add the above method.

I'm not sure about why you prefer A to B. Thanks for your suggestion, anyway :)

[Ellyster]

I think A is far better in this case.

Of course, I can just do B for my project in the language that I'm using (Ruby on Rails), but since it is a so common query I think it makes more sense to provide it in the MetaKGS API... rather than making everyone implement it in their own projects.

An cleaner alternative to A, if you want to preserve the KGS archive structure (a good design choice) might be to implement it under GET /api/archives/:user/rank

[anazawa]

Though GET /api/archives/:user/rank looked natural for me at first since the rank is derived from /api/archives/:user, a resource /api/archives represents a set of all games on KGS, and so I think queries followed preceded by the path should exclude some of those games (/rank excludes nothing). I would add /api/archives/:user/free or /api/archives/:user/ranked which represents a set of ranked or free games played by :user respectively.

In addition, MetaKGS is busy parsing HTML. I believe you can imagine how boring to maintain the parser is :-) That's why you feel MetaKGS APIs are too primitive to get your job done easily.

Instead, I'll write a Ruby client for MetaKGS for fun, while I'm a complete Ruby beginner :P

Update: replace "followed" with "preceded"

[Ellyster]

What about using GET /api/archives/:user/games instead for all games? It is a little off regarding the KGS Archives url, but seems way more easy extendable for the long run.

The other queries will be:

• GET /api/archives/:user/games/:year
• GET /api/archives/:user/games/:year/:month
• GET /api/archives/:user/games/:ranked
• GET /api/archives/:user/games/:free

And that way, in GET /api/archives/:user/ can be left for basic and processed information of the user, for example:

• Rank
• Link to the rank graph

[anazawa]

I agree the APIs should be easy to extend for the long run. As I explained before, /api/archives represents a set of all game on KGS, and so /archives can be renamed to /games. Thus paths you proposed can be rewritten as follows:

/api/archives/:user/games => /api/games/:user/games

Obviously "/games" is duplicated! I may be misunderstanding, though.

By the way, there are 3 layers in my mind:

1. Proxy to share HTTP responses from KGS (cache, it's very important to reduce HTTP requests to KGS)
2. HTML => JSON converter (MetaKGS APIs)
3. MetaKGS clients written in the user's favorite language

Layer 1 & 2, low level layers, are provided by MetaKGS. Yes, it's very unusual webapp structure but the only way to provide machine-readable resources since we don't have DB access to KGS. Though your request is to add convenience methods to low level layers, it should be added to Layer 3 instead (It can be derived from Layer 2). Feature requests to low levels without codes (patches) is basically unacceptable after all. I decided so after our discussion (That's my fault).

Currently, I'm working on Ruby client for fun, https://github.com/anazawa/metakgs.rb

[anazawa]

This issue looks inactive. Close temporarily. Feel free to reopen anytime :)

[anazawa]

@Ellyster I added #get_latest_rank_by_name to metakgs.rb 0.0.4. You can use the method as follows:

require 'metakgs'
rank = MetaKGS.get_latest_rank_by_name 'UserName'

[lmhsjackson]

So this endpoint ended up not done? It's a shame, I really thought this is super useful.

[anazawa]

I think so, too. Thanks for your comment :)