An open API? What we are thinking

We get asked about a game api roughly once a week, mostly by people running small clubs and by teachers who want to set up positions for students. This post is where we actually are on it: what a board game api would expose, the two problems we have not solved, and the order we plan to do things in. Nothing here ships tomorrow. If you just want to play, the play page is open.

Why we would build one

The requests split into two groups. Club organizers want their own match records in a spreadsheet so they can run a ladder without copying results out by hand. Teachers want to post one position and hand the same exercise to thirty students. Neither group wants another app. They want the data they already created on YiBoard to be usable somewhere else.

The second reason is selfish. The play page, the replay library and the rankings page all read the same match records through three separate queries. Rewriting those against one documented interface has been sat on our list for months. The public version would be that same interface with a lower rate limit.

What a first version would expose

• Match records: every move, the result, the time control, and the rating change for each side, as JSON
• Position setup: post a board state, get back the legal move list and an engine evaluation
• Engine moves: ask for one move at a fixed search budget, 500 ms today, and get the move with its score
• Leaderboard slices: the top N of any rank band, refreshed once an hour

What stays out matters more. The api would not return guest tokens, device lists, or any profile field that is not already public. That line is the one we drew in the open source board engine ecosystem, and it is not negotiable for us.

The two problems we have not solved

Rate limits are the easy one: pick a number, publish it, raise it later if the traffic turns out friendly. The hard one is bots. Under freestyle rules gomoku is close to solved, so a scripted client that plays clean offence beats most humans, and a few hundred of them would flatten the ladder inside a week. Our server validates every move, which stops people tampering with the client, but it cannot tell a strong human from a script.

Three ways out, and we have not picked one. Give api games their own ladder. Cap ranked games per token per day. Or launch unranked and decide later. We lean toward the last one, because it is the only option we could reverse without invalidating results people already earned.

The second problem is variants. Renju forbids certain double threes, freestyle does not. If a match record does not say which ruleset produced it, consumers will misread some games silently, and nobody notices until somebody publishes a broken analysis.

What a developer api for chess already proved

Chess has had this for years. Lichess runs a public HTTP api covering games, puzzles and engine analysis, and a large share of the tooling around online chess exists because somebody could read the data. A developer api for chess works partly because the rules are fixed and the notation is settled, so two programs always mean the same thing by the same string.

Gomoku has no equivalent. Engine projects are scattered, each with its own board format, and almost none can read a match record written by another. An open platform game for these games would fix that, but only if we publish the variant and the board size with every record, which is more metadata than most chess tooling bothers to carry.

What it would cost, and the order we are doing things in

Honest answer: more than the site costs now. Every open endpoint needs quotas, uptime monitoring, and someone to reply when a consumer breaks against a change. Our budget is small. The anti-cheat work and the xiangqi release both come first, and I would rather say that plainly than announce a date and then miss it.

The realistic sequence is read-only match records first, then position setup, then engine moves last, because that one burns compute on every call. If you want to argue with that ordering, the about page has a contact route and we do read it.

FAQ

Play a free game on YiBoard

YiBoard (yiboardgame.com) — 中华棋类，浏览器即玩，免费无注册。 去下一局 · 更多博客 · 玩法指南