L'API pubblica
Il catalogo dei giochi si legge in JSON, senza account: per un altro sito, un'applicazione, un bot…
- Documentazione interattiva (OpenAPI): /api/docs, si può provare ogni chiamata; la descrizione grezza: /api/docs.jsonopenapi
- I giochi:
GET /api/games - Un gioco:
GET /api/games/{slug} - Le categorie:
GET /api/categories, una categoria:GET /api/categories/{slug}
L'API è di sola lettura e autorizza le chiamate da qualsiasi sito (CORS). Le risposte vengono tenute in cache per un minuto.
I giochi
| Parametro | |
|---|---|
category |
una categoria (il suo slug) |
kind |
original (creazione), cpc (remake per Amstrad CPC), port (porting) |
order[rating], order[plays], order[publishedAt], order[title] |
l'ordinamento, asc o desc; più di uno di seguito per spareggiare. Di default: prima i più recenti |
page, itemsPerPage |
30 giochi per pagina, fino a 100 |
curl -g -H 'Accept: application/json' 'https://<ce site>/api/games?category=arcade&order[rating]=desc'
Ogni gioco:
| Campo | |
|---|---|
slug, title, description |
|
category, kind |
la sua categoria (slug), il suo tipo di progetto |
author |
il suo autore (identificativo GitHub) |
rating, ratings |
il suo voto medio su 5 (null senza voti), il numero di voti |
plays |
il numero di partite avviate |
engine, publishedAt |
la versione del motore JumPHP, la data dell'ultima pubblicazione |
forkOf |
il gioco di cui è un fork, altrimenti null |
url, play, source |
la sua pagina, il gioco a schermo intero, il suo codice consultabile |
image |
la sua immagine 640 × 360 (null se non ne ha una) |
repository, manifest |
il suo repository GitHub, l'elenco dei suoi file pubblicati (modalità remota di JumPHP) |
L'ordinamento per voto è lo stesso della pagina dei giochi: la media è tirata verso 3 finché un gioco ha pochi voti (tre voti fantasma), così un solo 5 su 5 non supera molti 4,5.
Pagine e JSON-LD
In JSON semplice (Accept: application/json), un elenco è un array. In JSON-LD
(Accept: application/ld+json, il formato predefinito), fornisce anche il numero totale (totalItems) e gli
indirizzi delle pagine (view.next, view.last):
{
"@id": "/api/games",
"totalItems": 42,
"member": [ { "@id": "/api/games/pong", "slug": "pong", "title": "PONG", "…": "…" } ],
"view": { "next": "/api/games?page=2", "last": "/api/games?page=2" }
}
Errori: 404 per un gioco o una categoria che non esiste (o non è più elencato), 422 per un parametro
non valido (kind=zzz), nel formato Problem Details (application/problem+json).