A standalone Spring Boot 4 service that fetches player, leaderboard type, and match statistics data for Age of Empires 1, 2, 3, and 4 from the unofficial WorldsEdge/RLink community API (aoe-api.worldsedgelink.com) and stores it in a local H2 database.
Requirement: Java 25. The Gradle wrapper is included in the repo, no separate install needed.
Run with: ./gradlew bootRun
On startup the application automatically syncs leaderboard data for all four games. Depending on data volume this can take tens of minutes. See Concurrency Model & Design Rationale below for why.
API docs: http://localhost:8080/swagger-ui/index.html
H2 console: http://localhost:8080/h2-console
JDBC URL: jdbc:h2:mem:test;LOCK_TIMEOUT=30000;DB_CLOSE_DELAY=-1;MODE=MySQL
Username: sa, password empty.
Known gap: LeaderboardController is not implemented yet, the /api/leaderboard endpoint returns empty. Data is written to the database but not exposed.
This project relies on an API that is not supported by the game developer and has been reverse engineered by the community. See github.com/librematch.
This service does not use an aggressive, fully-parallelized sync strategy.
The current implementation is:
- Sequential across games. One game's leaderboards fully sync before the next game starts.
- Bounded parallelism within a game. A fixed thread pool (size 6) processes leaderboards concurrently, but each leaderboard's own pagination stays sequential.
- Rate-limited. A semaphore plus a fixed delay keep requests well under the external API's limits.
A full sync of all four games with this strategy takes roughly 10-13 minutes.
aoe-api.worldsedgelink.com is an unofficial, community-reverse-engineered API (see librematch). It is not provisioned for high-throughput third-party traffic, and every request competes for the same limited rate budget the whole community relies on.
A highly concurrent sync would risk stricter rate limiting for everyone, with little real benefit: this is a background sync job, not a user-facing hot path. A sync that takes tens of minutes is a non-issue for a local, self-hosted service.
The slower design is a deliberate trade-off. Throughput is sacrificed for the long-term stability of a shared, unofficial API.
Given current data volume and the external API's rate limit, roughly 2-3 minutes is the theoretical lower bound for syncing all four games, even if data consistency guarantees were dropped entirely. Rate limiting alone prevents going faster than that.
A private implementation reaches this bound in practice: a full sync of AoE1, AoE2, AoE3, and AoE4 completes in 2.5-3 minutes. It also extends support to Age of Mythology, which is not yet part of this public repository. This solution is kept private to avoid enabling higher-volume traffic against the unofficial upstream API.