Rarity

Il problema

Nessun editore di carte collezionabili pubblica un'API. Se vuoi fare un deck builder o un'app per collezionisti parti dallo scraping, e per ogni gioco ricominci da capo. Il momento peggiore è la spoiler season, le settimane tra il primo reveal e l'uscita, quando le carte esistono solo come immagini e pagine web. Se in quel periodo ti inventi degli ID, il giorno dell'uscita li devi riscrivere, proprio quando servono.

Un ID dal reveal all'uscita

Ogni stampa ha un UUID ricavato da gioco, lingua e numero di collezione, così una carta tiene lo stesso ID dal giorno in cui viene rivelata a quello in cui arriva nei negozi. Ogni record dice anche da dove viene: lo stato, l'URL della fonte ufficiale, se i dati sono ancora parziali e com'è messa l'immagine.

Su una cosa non transigo. Entrano solo le carte rivelate ufficialmente. Niente leak, niente testo dedotto. Se una carta Naruto non ha un numero di collezione leggibile, resta fuori.

Ingest e prezzi

Ogni gioco ha un job che gira ogni ora. Scarica la fonte ufficiale, normalizza i dati, li valida contro lo schema pubblicato e scrive tutto in una sola transazione. Un hash del contenuto fa sì che una riga cambi solo quando cambia davvero qualcosa che il client vede, così ETag e changefeed non si muovono per niente.

Un altro job ogni giorno legge il listino pubblico di Cardmarket e aggiunge i prezzi europei a circa 10.000 stampe. E ogni ora esporto tutto il catalogo in un unico file compresso, per chi preferisce sincronizzarsi invece di sfogliare l'API pagina per pagina.

Il contratto non si rompe

Chi usa un'API si fida del contratto, quindi è la cosa che proteggo di più. Gli schemi Zod che validano richieste e risposte generano anche il documento OpenAPI, e se il file nel repo non corrisponde più al codice la CI fallisce. Ogni pull request passa anche un controllo delle breaking change rispetto a main e Schemathesis, un fuzzer che bombarda il server di richieste costruite dal documento pubblicato.