API Docs

Documentazione tecnica (iniziale) delle API della piattaforma. Per ora: Wiki (read-only). In futuro: progressione spoiler, build vault, telemetria leggera.

Stato: draft stabile Formato: JSON Versione: v1

šŸ“œIntroduzione

Le API di SalentoCore Platform servono a far ā€œparlareā€ contenuti e gioco. Lā€™obiettivo ĆØ semplice: una base stabile, poi crescita modulare.

Base URL

https://projectsalento.techgamesitalia.it

Negli esempi useremo BASE_URL.

Formato risposta

Tutte le risposte sono JSON con struttura consistente.

{ "ok": true, "data": { ... }, "meta": { "version": "v1" } }

šŸ”Autenticazione

Per ora (v1) le API Wiki pubbliche sono accessibili senza token.

Le rotte pubbliche non richiedono login. In futuro, per contenuti ā€œteam/adminā€ e per funzioni sensibili, useremo:

  • Session cookie (browser)
  • API key (in-game / tooling)
  • Scope: public / team / admin

Nota: meglio tenere lā€™API key lato server o nel backend del gioco, non nel client puro.

āš ļøErrori & codici

{ "ok": false, "error": { "code": "NOT_FOUND", "message": "Risorsa non trovata" } }
  • 200 OK
  • 400 BAD_REQUEST
  • 401 UNAUTHORIZED
  • 403 FORBIDDEN
  • 404 NOT_FOUND
  • 500 SERVER_ERROR

šŸ“šWiki API (v1)

La Wiki ĆØ la spina dorsale: creature, luoghi, reperti, personaggi, brand, armi. Lā€™API serve per:

  • mostrare voci nel sito pubblico
  • integrare ā€œlore unlockā€ nel gioco (futuro)
  • caricare preview icone e contenuti

Namespace: /api/v1

šŸ§¾Lista voci

GET /api/v1/wiki

Parametri query:

  • type = creature|luogo|reperto|personaggio|brand|arma (opzionale)
  • q = ricerca testo (opzionale)
  • limit = default 30 (opzionale)
  • page = default 1 (opzionale)
curl -s 'BASE_URL/api/v1/wiki?type=creature&limit=12&page=1'
{ "ok": true, "data": [ { "slug": "scazzamurreddhu", "title": "Scazzamurreddhu", "type": "creature", "visibility": "public", "icon_path": "/img/wiki/icons/Scazza_Icon.png", "updated_at": "2026-02-18 10:12:00" } ], "meta": { "version": "v1", "page": 1, "limit": 12, "total": 42 } }

šŸ“ŒVoce singola

GET /api/v1/wiki/{slug}

curl -s 'BASE_URL/api/v1/wiki/scazzamurreddhu'
{ "ok": true, "data": { "slug": "scazzamurreddhu", "title": "Scazzamurreddhu", "type": "creature", "visibility": "public", "icon_path": "/img/wiki/icons/Scazza_Icon.png", "body_public": "

...

", "updated_at": "2026-02-18 10:12:00" }, "meta": { "version": "v1" } }

Nota: il contenuto body_public puĆ² contenere HTML (come nel sito).

šŸ•ÆļøVisibilitĆ  & spoiler

Ogni voce ha un campo visibility: public, team, admin.

  • public: disponibile al pubblico
  • team: disponibile a editor/admin e (futuro) a giocatori ā€œsbloccatiā€
  • admin: solo admin

Roadmap: ā€œspoiler unlockā€ per slug, collegato a progressione in-game.

ā±ļøRate limit

Per ora nessun rate limit aggressivo. In release pubblica:

  • Public: 60 req/min per IP
  • Auth: 120 req/min
  • Admin: limit alto + logging

Obiettivo: protezione senza rovinare la fluiditĆ .

šŸ§©Changelog

v1.0 - Wiki API read-only: list, entry, search - visibility: public/team/admin (enforced lato piattaforma) v1.1 (planned) - API keys (scopes) - unlock spoiler per account / progressione - endpoint posts/news read-only