Integrare e ospitare l'AI: API, webhook e container

In una frase

Scelto il modello e dove farlo girare (vedi la guida sul dove), restano due domande da ingegneri: come si collega l'AI ai tuoi sistemi, e come la impacchetti perché giri sempre uguale e regga il traffico. Le risposte sono due famiglie di strumenti — le API (i "tubi" che fanno parlare i software) e i container (le "scatole" che impacchettano e ospitano).

Due domande, due famiglie di strumenti

COME SI COLLEGA?                 COME SI OSPITA?
le API (i tubi)                  i container (le scatole)
REST · GraphQL · webhook         Docker · Kubernetes

È il livello sotto la guida "Dove far girare l'AI": lì sceglievi quale modello e dove; qui vedi come lo colleghi ai tuoi software e come lo impacchetti per la produzione.

Parte 1 — Le API: come i software si parlano

Un'API è un contratto che fa comunicare due software. Per integrare l'AI (e i sistemi in generale) ricorrono tre approcci: i primi due sono pull (chiedi tu), il terzo è push (ti notificano).

• REST — chiedi a un indirizzo. Le risorse sono URL, manipolate con i verbi HTTP (GET / POST / PUT / DELETE). Semplice, senza stato, in JSON: è lo standard de-facto del web.
• GraphQL — chiedi esattamente ciò che ti serve. Un solo endpoint, e nella query elenchi i campi che vuoi → niente dati di troppo o di meno, con uno schema tipizzato che si auto-documenta.
• Webhook — è il server che chiama te. Una "API al contrario": quando accade un evento (un pagamento, un nuovo lead), il server manda una POST al tuo indirizzo con i dati. Tempo reale, senza dover continuare a chiedere.

	REST	GraphQL	Webhook
Chi inizia	tu (pull)	tu (pull)	il server (push)
Come	URL + verbi HTTP	1 endpoint, scegli i campi	POST al tuo URL su evento
Forte per	CRUD, API pubbliche	dati complessi/variabili, poche chiamate	reagire a eventi in tempo reale

In pratica si combinano: REST o GraphQL per leggere e scrivere, webhook per gli eventi (è così che un nuovo lead fa partire da solo una pipeline su n8n o un'azione dell'AI).

È lo stesso meccanismo del function calling (vedi la guida sugli agenti): quando l'AI "usa uno strumento", dietro c'è una chiamata API. I webhook vanno protetti (verifica della firma) e gestiti con retry e idempotenza — è il mondo esterno a bussare a casa tua.

Parte 2 — I container: impacchettare e ospitare

Docker — "sul mio computer funziona", risolto

Docker impacchetta un'applicazione con tutte le sue dipendenze (codice, runtime, librerie, configurazioni) in un container: un'unità leggera e portabile che gira uguale ovunque. Addio al classico "sul mio computer funziona".

• A differenza di una macchina virtuale, i container condividono il kernel del sistema → molto più leggeri e veloci.
• Il flusso:

Dockerfile  ──►  immagine  ──►  container (in esecuzione)
(la ricetta)     (il pacchetto)   (una o più copie isolate)

• Nell'AI: distribuire un servizio (l'API di un modello, un'app RAG) in modo riproducibile dallo sviluppo alla produzione, isolando le versioni di Python e delle librerie ML.

Kubernetes — gestire i container in massa

Se Docker crea i container, Kubernetes (K8s) li orchestra su tanti server: li distribuisce, li scala, li riavvia se cadono, bilancia il traffico. Tu descrivi lo stato desiderato ("voglio 3 copie sempre attive") e lui lavora per mantenerlo (self-healing, auto-scaling).

• Nell'AI: servire modelli e API ad alta disponibilità e a traffico variabile. È il sostrato tipico dell'MLOps/LLMOps a scala (vedi la guida sulla produzione).
• Spesso è troppo. Per un progetto piccolo Kubernetes è sovradimensionato: bastano un container singolo o un servizio gestito (es. Cloud Run). Le grandi nuvole offrono K8s "chiavi in mano" (EKS, GKE, AKS) quando serve davvero.

Quanto ti serve?
  1 servizio · poco traffico         ──►  Docker (un container) o servizio gestito
  tanti servizi · traffico su e giù  ──►  Kubernetes (scaling + self-healing)
  + alta disponibilità

Per una PMI: la regola di buon senso

• API: REST copre il 90% dei casi; webhook per le automazioni (n8n / Zapier). GraphQL solo se i tuoi dati sono complessi e variabili.
• Hosting: parti con un container (o un servizio gestito). Non ti serve Kubernetes per cominciare — sali solo quando scala e disponibilità lo impongono.
• Sicurezza: proteggi i webhook (firma + retry) e attenzione alla provenienza delle immagini Docker (vulnerabilità).

In sintesi

• Scelto il modello, restano due domande: come collegarlo (API) e come ospitarlo (container).
• API: REST (chiedi a un indirizzo) · GraphQL (chiedi i campi esatti) · webhook (ti notificano gli eventi). Si combinano.
• Container: Docker impacchetta ("gira uguale ovunque"); Kubernetes orchestra in massa (scaling, self-healing) — ma è spesso troppo per i piccoli.
• Regola PMI: parti semplice (REST + un container o servizio gestito); Kubernetes e GraphQL solo quando il problema lo chiede davvero.

Fonti

• REST: R. Fielding, Architectural Styles and the Design of Network-based Software Architectures, 2000 — roy.gbiv.com
• GraphQL: specifica ufficiale — spec.graphql.org
• Kubernetes (dall'esperienza Google "Borg"): Verma et al., Large-scale cluster management at Google with Borg, 2015 — research.google
• Docker: documentazione ufficiale (standard OCI) — docs.docker.com

Materiale informativo a cura di Rayer Group. Non costituisce consulenza tecnica o legale personalizzata: per il caso concreto valutiamo insieme la situazione specifica.