Improving API

[JohnChernoff]

Would be helpful to have a way for accounts labeled as bots to programatically access lichess features such as currently played games, moves, chat, etc. The model could perhaps be similar to the "datagrams" ICC employs (http://www6.chessclub.com/resources/formats/formats.txt).

• Zug

[Unihedro]

Disclaimer: I do not understand what a "datagram" is and only guessed its nature after skimming through the manual you linked for five minutes. When you write something, and someone else doesn't understand it after the amount of reading they put into it, that means you didn't write it clearly enough. It's up to them to rewrite it until it is clear. Clear enough even for stupid people, for lazy people, for people who are reading too quickly, for people who are operating in their second language, for people who guess after half a sentence what the whole thing is about and then start replying without even reading the rest.

If the feature is solely to provide the UI in a more parseable format, being a responsive layout Lichess's DOM and inlined scripts doesn't seem to have such a demand:

/tournament

JSON.parse($('script:contains(LichessTournamentSchedule)').text().match(/{.+}/)[0])
... Object {
  created: Array[28] of [
    Object {..., fullName: "Reshevsky Arena", ...},
    Object {..., fullName: "Daily SuperBlitz Arena", ...},
    Object {..., fullName: "Hourly Bullet Arena", ...},
    ...
  ],
  finished: Array[10],
  started: Array[6]
}

/simul/

lichess.simul.data
... Object {
  applicants: Array,
  fullName: "Lead simul",
  host: Object {
    gameId: ...,
    id: ...,
    rating: ...,
    ...
  },
  id: ...,
  isCreated: false,
  isFinished: false,
  isRunning: true,
  name: "Lead",
  ...
}

If you have a specific API endpoint to open to request that doesn't already exist (visit the API documentation in the README and the mobile API in /doc), request that instead.

[ddugovic]

@JohnChernoff , @ornicar , and myself were part of a brief discussion earlier today. John's intent isn't to follow an existing ICC protocol but to expose API(s) by which authenticated bots can search and spectate live games (and maybe live examine boards?). I think his motivation for linking to ICC's protocol(s) was to show he understands that an API need not be limited by what he's currently interested in.

@JohnChernoff , we'd appreciate if here you could explain specific use cases/motivations...

[Unihedro]

I agree that the API could use improvements, but the only use case that has ever went up so far was for the mobile app.

[JohnChernoff]

I'm confused by the original admonition. What could I have written to make the term "datagram" clearer? Perhaps this is a language issue, but the document I linked to seems relatively coherent and concise (though perhaps only if one is already familiar with ICC).

Anyhow, yes, I was, at the risk of repeating myself, imagining an API to allow convenient programmatic access to various lichess features, such as but not limited to creating a game, making moves, watching games, kibitzing, examining, and so forth and so on. I referred to the Internet Chess Server model above because I found it to employ a straightforward mechanism for such things, but certainly didn't mean to suggest a slavish imitation of it.

Finally, if it would be better to request an extension of the DOM for each "end point" individually, so be it, though it strikes me as redundant in the extreme to do so and I don't quite understand how it could be used to actively issue commands (starting games, making moves, drawing arrows, etc.).

Apologies,

• John

[Unihedro]

In other words, you want the existing API to be expanded to:

1. create a game
2. make moves
3. watch games
4. access chat systems

1-3 are already covered by the mobile API (see documentation in /doc). 4 doesn't have much of an use case.

[JohnChernoff]

Again, apologies, I didn't notice this API, assuming (presumably wrongly) that it was for mobile apps only. It covers most of what I was imagining (sans chat). That said, essentially all features that could conceivably allow one to create a non-web lichess client would be useful I think, but that's asking a bit much for now. My original motive was to create a bot to keep track of "interesting" events on lichess each day and present them in a matter not completely unlike, say, a sports show does (for Americans, perhaps something akin to ESPN's "Sportscenter"). The bot would follow as many games as possible, sort them by highest rating, title, spectators, kibitzes, material fluctuation, etc.,and then be utilized (likely by a streamer) for commentary. Perhaps this is already doable, but if not I think it would be a sufficiently entertaining addition to the site to warrant the trouble of extending the API a bit further.

[Unihedro]

No need to reiterate on proof on concept ideas. Please state what you'd like the API to be able to do that isn't currently available. Ideally in a list with examples of how each of the items in the list can be used / aren't going to collect dust.

[ddugovic]

@JohnChernoff and I would like an API which allows the following:

1. Engine users may seek rated and causal games
2. Engine users may accept rated and causal seeks (if the seek specifies "Allow Computer"); or at least on my dev instance allow for this
3. Engine vs engine games may be played
4. All users may filter live games by highest rating, title, spectators, kibitzes, material fluctuation, etc.
5. Engine users may kibitz on player games
6. Human users may analyze games

Basically, anything a player user may do, an engine user may do; and vice versa. And additional live game filtering capability would be nice too, to produce a stream entertaining to a live audience in a similar manner to how FIDE & USCF chess events are covered/streamed on other sites.

I understand that the idea of allowing engine users into tournaments, simuls, etc. would be unpopular, but in my opinion the benefits of allowing engines to play games outweigh the negative consequences.

EDIT: Okay, I agree that it makes sense to make #1339 a separate issue.

[Unihedro]

#issuecomment-166140459 1 + 2 + 3 + 5 -> #1339 - it's a huge and different feature altogether

[JohnChernoff]

OK, have had a bit of time to examine the lichess API but am not seeing how to programatically access a list of all current games on the server. Am I missing something?

• John

[ddugovic]

:+1: The API doesn't seem to offer a way to list all live games on the server; or some equivalent of the ICC/FICS gin command which announces every time a game is created.

[Unihedro]

This ticket has been inactive for too long. It discusses about requests for the API set that, while extending maintenance support and dev hours, doesn't seem to have valid use cases and may only have a questionable degree of effectiveness. As a result, I'm deferring it by closing. While I personally agree that a full support for an improved programming interface is largely beneficial, it's clear that Lichess isn't going to get a public API unless people will use them, clearly.

If such relevant requests or features are deemed to be possible to be implemented and there are resources that will be consistently useful, please create a new ticket about it and reference this one with #1253.

Also: Some of the ideas here has already been made into separate issues, while the ones that aren't likely to happen simply sink, so there's no need to duplicate the ideas mentioned here.

[ornicar]

:+1: