API Reference

Le spec OpenAPI di web e worker sono generate automaticamente dai moduli Zod sotto packages/web/lib/openapi/ e packages/worker/src/openapi/. Le relative pagine sono costruite da fumadocs-openapi e si aggiornano eseguendo pnpm gen:openapi.

Le API del modulo OMS sono attualmente documentate in un catalogo dedicato: le route Next.js OMS non fanno ancora parte del generatore OpenAPI. Questa distinzione è intenzionalmente esplicita, così la documentazione non presenta come completo uno schema che oggi copre soltanto web e worker.

Spec scaricabili

• 📄 openapi/web.json — API pubbliche del web app
• 📄 openapi/worker.json — API interne del worker Fastify
• Catalogo API OMS — endpoint, permessi, idempotenza ed errori operativi

Come navigare

Ogni operazione ha la sua pagina. Lo slug segue lo schema <path-segments>/<method>:

Lo slug rimuove le parentesi graffe dai path params: {id} → id, {importId} → importid, ecc. Tutto lowercase.

La sidebar a sinistra elenca le operazioni presenti nelle due spec generate, raggruppate per tag. Per le route OMS usa il catalogo manuale finché non sarà disponibile la terza spec oms.json.

Pattern di risposta

Le route JSON applicative usano normalmente l'envelope:

{ "data": { ... } }           // 2xx
{ "error": "Messaggio" }      // 4xx / 5xx

Status HTTP: 200/201/202/204 (OK), 400 (input), 401 (no auth), 403 (forbidden), 404 (not found), 409 (conflict), 422 (validazione semantica), 500 (internal).

Export, feed, PDF, etichette, SSE e metriche sono eccezioni: restituiscono file, stream o testo con il relativo Content-Type, non un envelope JSON.

Autenticazione

Gli endpoint web e OMS, salvo quelli dichiarati pubblici, richiedono una sessione NextAuth valida via cookie HttpOnly authjs.session-token. Login via Keycloak — vedi Auth & SSO. Le route OMS applicano inoltre entitlement, area e permesso di scrittura dell'organizzazione attiva.

Gli endpoint worker (/internal/*, /events/*) usano header x-internal-secret per la comunicazione web↔worker; non sono esposti al browser.

Il playground inline esegue le chiamate ma non è autenticato (cookie HttpOnly non sono accessibili da JS). Per testare interattivamente, fai login su exp.fire-feed.com in un'altra tab e usa curl --cookie-jar.

Convention per chi contribuisce

Aggiungere un endpoint:

1. Definisci lo Zod schema in packages/web/lib/openapi/<dominio>.ts (o packages/worker/src/openapi/internal.ts).
2. Chiama defineEndpoint({ method, path, tags, summary, description, request, responses }).
3. Nel route.ts, importa lo schema body/params e chiama .safeParse() su request.json().
4. pnpm gen:openapi → aggiorna web.json e worker.json.
5. Commit dello spec aggiornato (il CI guard pnpm gen:openapi:check blocca i PR senza spec aggiornato).