How about GraphQL? (Including a bridge and bonus Python API)

I am wondering if there are any plans of adding a GraphQL endpoint? Looking at the examples of what people are working on, it seems as if it could make things a lot easier for both consumers of the API, as well as potentially decreasing the load on the server.

I have put together a simple bridge for trying this out on GitHub in case anyone is interested (and it includes a bonus Python interface to the current API as well — does not support everything yet, but is easy to extend). The bridge can also be useful as a datasource for site generators and such.

For those who haven't looked at GraphQL it is kind of an alternative to REST APIs, but with a couple of potential benefits:

• Allows you to specify the data you want in a single requests (mostly) 
• You only get the data you specify — less traffic
• Has a very simple syntax which is easier than figuring out which endpoints to hit — and it is possible for tools to provide not only validation but also auto-completion and documentation for requests (see GraphiQL)
• Better for future-proofing, since the requests aren't tied to specific endpoints with certain parameters it is easy to add fields as needed (and has  a way of marking deprecated fields)
• Since you specify the data you want in one go, there are more possibilities for back-end optimizations (and adding filters and such).

Some examples: (I have added Python code to retrieve the same data which often looks similar to the GraphQL queries, but remember that it generates a whole series of requests which tends to be quite slow)

Checking if a player is online:

This is only one request in both cases, but illustrates the GraphQL syntax (note that I have just tried to map the existing API to GraphQL as directly as possibly, and there is plenty of room for improvements).

GraphQL:

{
  player(username: "chrka") {
    isOnline
  }
}

Python:

chesscom.lookup_player("chrka").is_online()

Getting player information for a club:

You can specify variable in GraphQL queries (as well as breaking out fragments) to simplify reuse. Here we request the name and description of a given club, and retrieve info about the members (username, title if any, last time being online, when they joined the club and when they were active last, and their Daily chess ratings)

GraphQL:

query ClubRoster($club: String) {
  club(key: $club) {
    name
    description
    members {
      username
      title
      lastOnline
      joinedClub(key: $club)
      lastActiveInClub(key: $club)
      dailyRating: rating(category: "chess_daily")
      daily960Rating: rating(category: "chess960_daily")
    }
  }
}

Python:

def club_roster(club_key):
  club = chesscom.lookup_club(club_key)
  name = club.name()
  description = club.description()
  roster = []
  for member in club.members():
    roster.append({
    'username': member.original_username(),
    'title': member.title().value,
    'last_online': member.last_online(),
    'joined_club': member.last_active_in_club(club_key),
    'last_active_in_club': member.last_active_in_club(club_key),
    'daily_rating': member.rating('chess_daily'),
    'daily960_rating': member.rating('chess960_daily')
  })
  return roster

Requires a total number of (2 + 3 * number of members) requests. (club profile, club members; members: profile, clubs, stats which returns a lot of info we don't need. 

Hey Chris!  Great work!

Yeah, we have some plans regarding GraphQL. We already have POC in place but we're still doing a detailed research.

Thanks for sharing your work on Github, I really like it!

Zdravo Žarko!

Glad to hear it. Yeah, I can think of several places where GraphQL can be useful other than the public API as well