Rarity

The problem

No trading card publisher has an API. If you want to build a deck builder or a collection app, you start by scraping, and you start over for every game. The worst moment is spoiler season, the weeks between the first reveal and the release, when the cards exist only as images and web pages. If you make up your own IDs in that window, you have to rewrite them on release day, exactly when they matter.

One ID from reveal to release

Every printing gets a UUID derived from game, language and collector number, so a card keeps the same ID from the day it's revealed to the day it's in shops. Every record also says where it comes from: its status, the official source URL, whether the data is still partial, and the state of the image.

There's one thing I don't bend on. Only officially revealed cards go in. No leaks, no guessed text. If a Naruto card has no readable collector number, it stays out.

Ingest and prices

Each game has its own job that runs every hour. It fetches the official source, normalises the data, validates it against the published schema and writes everything in a single transaction. A hash of the content means a row only changes when something a client can actually see changes, so ETags and the change feed don't move for nothing.

Another job reads the public Cardmarket price guide every day and adds EU prices to about 10,000 printings. And every hour I export the whole catalog as one compressed file, for anyone who'd rather sync than page through the API.

Keeping the contract

People who use an API trust the contract, so that's what I protect the most. The Zod schemas that validate requests and responses also generate the OpenAPI document, and if the committed file no longer matches the code, CI fails. Every pull request also runs a breaking change check against main and Schemathesis, a fuzzer that hammers the server with requests built from the published document.