API per sviluppatori

L'API di Joytime dà accesso a catalogo, schede, trailer, recensioni e al diario degli utenti. È quella usata dalle app ufficiali per iOS e Android, sullo stile dell'API di TMDB.

Per iniziare

Indirizzo base: /api/v1
Ogni richiesta porta una chiave: header X-Api-Key: jt_… oppure parametro ?api_key=.
Le azioni personali (diario, like, commenti, follow) richiedono anche il token utente: Authorization: Bearer <token>, ottenuto con POST /auth/login. Il token dura 30 giorni.
Limite: 50 richieste ogni 10 secondi per chiave; oltre si riceve 429.

curl -H "X-Api-Key: jt_…" "{sito}/api/v1/games?query=zelda"

curl -H "X-Api-Key: jt_…" \
  "{sito}/api/v1/games/12?append_to_response=videos,screenshots,reviews,similar"

Formati e regole

Elenchi paginati: { page, results, total_pages, total_results }.
Errori: { success: false, status_code, status_message } con codici HTTP 401, 404, 422, 429.
Voti: scala 0,5–5 a mezzi punti, come le stelle del sito.
Immagini: URL già pronti in più misure WebP (w320, w640, w1280, w1920) più original. Scegli la misura in base allo spazio sullo schermo.
Trailer: mp4 e hls si riproducono direttamente con AVPlayer o ExoPlayer; per youtube usa key con il player di YouTube.
ID: gli ID Joytime sono permanenti; per collegare i tuoi dati usa anche /find con gli ID degli store.

Accesso con Google, Apple, Twitch e Steam dalle app: avverrà tramite il browser di sistema (ASWebAuthenticationSession / Custom Tabs) con ritorno all'app; verrà aggiunto insieme alle app.

Generale

GET/configuration

Costanti per le app: stati del diario, tipi, console, misure delle immagini, ordinamenti.

GET/home

Tutta la home in una richiesta: vetrina (featured, con reason new/upcoming/trending), file (tendenza, top 10, per console, in arrivo, recenti), liste popolari (e degli amici con il token) e ultime recensioni.

GET/platforms

Piattaforme, con la console di appartenenza.

GET/genres

Elenco chiuso dei generi.

Giochi

GET/games

Ricerca e scoperta, paginata (20 per pagina).

`query`	query · string	Testo da cercare: titolo, sviluppatore, editore. Trova anche i giochi non ancora usciti. Ogni risultato ha match: "exact" (stesso titolo, ignorando maiuscole, accenti, ™ e punteggiatura) o "partial"; gli exact arrivano prima.
`year`	query · integer	Anno di uscita (es. 2023): distingue remake e omonimi, come year di TMDB.
`console`	query · string	nintendo, playstation, xbox, pc, mobile.
`platform`	query · string	Slug della piattaforma (es. ps5, switch).
`genre`	query · string	Un genere dell'elenco.
`sort`	query · string	popular (predefinito), trending, growing, anticipated, top_rated, recent, upcoming, title. Le tendenze includono fonte, rilevazione e confronti in trends.evidence e trends.growth.
`page`	query · integer	Pagina, da 1 a 500 (predefinita 1).

GET/games/{id}

Scheda completa. Con append_to_response aggiungi altri dati nella stessa risposta.

`id`*	percorso · integer	ID Joytime del gioco.
`append_to_response`	query · string	Separati da virgola: videos, screenshots, reviews, similar, more_from_developer, community, my_entry (richiede token).

GET/games/{id}/videos

Trailer: mp4 e hls riproducibili direttamente (AVPlayer/ExoPlayer), youtube con il suo ID.

id* percorso · integer ID Joytime del gioco.

GET/games/{id}/screenshots

Screenshot in tutte le misure.

id* percorso · integer ID Joytime del gioco.

GET/games/{id}/reviews

Recensioni, le più apprezzate prima.

`id`*	percorso · integer	ID Joytime del gioco.
`page`	query · integer	Pagina, da 1 a 500 (predefinita 1).

GET/games/{id}/similar

Giochi simili per genere.

id* percorso · integer ID Joytime del gioco.

GET/find/{external_id}

Trova un gioco da un ID esterno (come /find di TMDB).

`external_id`*	percorso · string	ID sullo store (es. 1245620).
`source`*	query · string	steam, playstation, nintendo, xbox, igdb, wikidata, wikipedia.

POST/games/lookup

Abbina in blocco fino a 200 giochi di un catalogo esterno: popolarità, tendenza, voto IGDB/Metacritic.

items* corpo JSON · array [{ key, title, igdb_id?, platform? }], al massimo 200.

Utenti

GET/users/{username}

Profilo pubblico: statistiche, online, social, follower.

username* percorso · string Nome utente.

GET/users/{username}/games

Diario di un utente.

`username`*	percorso · string	Nome utente.
`status`	query · string	playing, played, completed, abandoned o wishlist.
`page`	query · integer	Pagina, da 1 a 500 (predefinita 1).

GET/users/{username}/reviews

Recensioni di un utente.

`username`*	percorso · string	Nome utente.
`page`	query · integer	Pagina, da 1 a 500 (predefinita 1).

POST/users/{username}/followtoken utente

Segue o smette di seguire; risponde con lo stato finale.

username* percorso · string Nome utente.

Liste

GET/lists

Liste pubbliche popolari (like e follower recenti), 20 per pagina.

page query · integer Pagina, da 1 a 500 (predefinita 1).

POST/liststoken utente

Crea una lista.

`title`*	corpo JSON · string	Titolo, da 2 a 80 caratteri.
`description`	corpo JSON · string	Descrizione, fino a 1000 caratteri.
`visibility`	corpo JSON · string	public (predefinito: profilo e liste popolari) o private (solo chi ha il link).
`mode`	corpo JSON · string	solo (predefinito) o together (anche i collaboratori invitati possono modificarla).
`ranked`	corpo JSON · boolean	Classifica numerata: l'ordine conta.

GET/lists/{code}

Lista completa con i giochi (rank, nota, chi l'ha aggiunto); con il token anche my_access.

code* percorso · string Codice della lista (6 caratteri).

PUT/lists/{code}token utente

Modifica titolo e impostazioni (solo il proprietario).

`code`*	percorso · string	Codice della lista (6 caratteri).
`title`*	corpo JSON · string	Titolo, da 2 a 80 caratteri.
`description`	corpo JSON · string	Descrizione, fino a 1000 caratteri.
`visibility`	corpo JSON · string	public (predefinito: profilo e liste popolari) o private (solo chi ha il link).
`mode`	corpo JSON · string	solo (predefinito) o together (anche i collaboratori invitati possono modificarla).
`ranked`	corpo JSON · boolean	Classifica numerata: l'ordine conta.

DELETE/lists/{code}token utente

Elimina la lista (solo il proprietario).

code* percorso · string Codice della lista (6 caratteri).

POST/lists/{code}/itemstoken utente

Aggiunge un gioco (proprietario o collaboratori).

`code`*	percorso · string	Codice della lista (6 caratteri).
`game_id`*	corpo JSON · integer	ID Joytime del gioco.
`note`	corpo JSON · string	Nota, fino a 280 caratteri.

PUT/lists/{code}/items/{game_id}token utente

Sposta il gioco (position, 1 = primo) o ne cambia la nota.

`code`*	percorso · string	Codice della lista (6 caratteri).
`game_id`*	percorso · integer	ID Joytime del gioco.
`position`	corpo JSON · integer	Nuova posizione.
`note`	corpo JSON · string	Nota.

DELETE/lists/{code}/items/{game_id}token utente

Toglie il gioco dalla lista.

`code`*	percorso · string	Codice della lista (6 caratteri).
`game_id`*	percorso · integer	ID Joytime del gioco.

POST/lists/{code}/followtoken utente

Segue o smette di seguire la lista; risponde con lo stato finale.

code* percorso · string Codice della lista (6 caratteri).

POST/lists/{code}/liketoken utente

Mette o toglie il like; risponde con lo stato finale.

code* percorso · string Codice della lista (6 caratteri).

POST/lists/{code}/copytoken utente

Copia la lista tra le proprie (privata, solo mia).

code* percorso · string Codice della lista (6 caratteri).

GET/users/{username}/lists

Liste di un utente (le private solo al proprietario del token).

username* percorso · string Nome utente.

GET/games/{id}/lists

Liste pubbliche che contengono il gioco.

id* percorso · integer ID Joytime del gioco.

Recensioni

GET/reviews/{id}

Recensione con i commenti.

id* percorso · integer ID della recensione.

POST/reviews/{id}/liketoken utente

Mette o toglie il like; risponde con lo stato finale.

id* percorso · integer ID della recensione.

POST/reviews/{id}/commentstoken utente

Commenta una recensione.

`id`*	percorso · integer	ID della recensione.
`content`*	corpo JSON · string	Testo, da 2 a 2000 caratteri.

Accesso

POST/auth/login

Accesso con nome utente/email e password: restituisce il token da usare come Authorization: Bearer.

`login`*	corpo JSON · string	Nome utente o email.
`password`*	corpo JSON · string	Password.

POST/auth/logouttoken utente

Invalida il token.

Il mio account

GET/metoken utente

Profilo dell'utente del token.

GET/me/gamestoken utente

Il mio diario.

`status`	query · string	playing, played, completed, abandoned o wishlist.
`page`	query · integer	Pagina, da 1 a 500 (predefinita 1).

GET/me/games/{id}token utente

La mia voce di diario per un gioco (entry: null se non c'è).

id* percorso · integer ID Joytime del gioco.

PUT/me/games/{id}token utente

Aggiunge o aggiorna un gioco nel diario, con voto e recensione.

`id`*	percorso · integer	ID Joytime del gioco.
`status`*	corpo JSON · string	playing, played, completed, abandoned, wishlist.
`rating`	corpo JSON · number	Da 0.5 a 5 a mezzi punti; null per nessun voto. Non ammesso con wishlist.
`platform_id`	corpo JSON · integer	Piattaforma su cui ci hai giocato (tra quelle del gioco).
`hours`	corpo JSON · number	Ore di gioco.
`review`	corpo JSON · string	Recensione; vuota la rimuove.
`spoiler`	corpo JSON · boolean	La recensione contiene spoiler.

DELETE/me/games/{id}token utente

Toglie il gioco dal diario (e la recensione).

id* percorso · integer ID Joytime del gioco.

GET/me/liststoken utente

Le mie liste (anche private e quelle in cui collaboro) e quelle che seguo.

GET/me/consolestoken utente

Xbox e PlayStation collegati: stato online, gamerscore o livello trofei, giochi con ore e progressi (joytime_id se il gioco è nel catalogo).

GET/me/feedtoken utente

Attività delle persone che segui.

Per una chiave scrivi ai moderatori. Usando l'API accetti i termini d'uso.