Cos'è un'API? Guida in parole semplici per chi costruisce app

Un'API (application programming interface) è un modo definito con cui un software chiede a un altro dei dati o gli fa fare qualcosa. La tua app invia una richiesta in un formato concordato — “dammi le prenotazioni di domani”, “addebita 20 euro su questa carta”, “riassumi questo testo” — e l'altro sistema restituisce una risposta strutturata. Le API sono il modo in cui le parti di un'app comunicano tra loro, e il modo in cui la tua app usa servizi esterni come pagamenti, email, mappe e AI.

Perché le API contano quando costruisci con l'AI

Quasi ogni app utile è fatta di parti che comunicano tramite API:

• All'interno della tua app, le schermate nel browser chiamano l'API del tuo backend per caricare e salvare i dati.
• All'esterno della tua app, il tuo backend chiama le API di altre aziende: Stripe per accettare pagamenti, un fornitore di email per inviare le ricevute, un fornitore di modelli AI per generare testo.

Quando chiedi a un AI builder di “accettare pagamenti” o “aggiungere un riassunto AI”, in realtà sta scrivendo codice che chiama un'API. Conoscerne le basi ti aiuta a capire cosa ha bisogno l'AI da te (di solito un account presso quel servizio e una chiave API), dove le cose possono andare storte e quanto costeranno.

Un'analogia quotidiana

Pensa a un ristorante. Non entri in cucina a cucinare. Leggi il menù, dici al cameriere cosa vuoi in un modo che la cucina capisce, e il cameriere ti porta il piatto — oppure ti dice che il piatto è esaurito.

• Il menù è la documentazione dell'API: un elenco di ciò che puoi chiedere e di come chiederlo.
• Il cameriere è l'API: l'unico modo concordato con cui le richieste entrano e le risposte escono.
• La cucina è l'altro sistema: non ti serve sapere come funziona al suo interno.
• L'ordine è la richiesta; il piatto è la risposta.

La cucina può cambiare forni e personale senza che tu te ne accorga, purché il menù resti lo stesso. Questo è il vero valore di un'API: permette a due sistemi di lavorare insieme senza che nessuno dei due debba sapere come è costruito l'altro.

Come funziona una richiesta API web

La maggior parte delle API che incontrerai sono API web che funzionano tramite HTTP, lo stesso protocollo che usa il tuo browser. Ogni richiesta ha alcune parti:

E ogni risposta ha:

JSON (JavaScript Object Notation) è un semplice formato di testo fatto di nomi e valori tra parentesi graffe. È il modo standard con cui le API web scambiano dati.

REST: lo stile più comune

REST è una convenzione molto usata per progettare API web. Ogni tipo di oggetto ha un proprio URL, e i metodi standard indicano cosa gli stai facendo. Ecco come potrebbe apparire un'API REST per un'app di prenotazioni:

Esiste anche PUT, che per convenzione sostituisce un intero record, mentre PATCH modifica solo i campi che invii.

I codici di stato che vedrai più spesso:

Quando la tua app si rompe, il codice di stato è spesso l'indizio più rapido. Un 401 da un fornitore di pagamenti di solito significa una chiave API mancante o sbagliata; un 429 significa che stai chiamando troppo spesso.

REST non è l'unico stile — esistono anche GraphQL e API in stile RPC — ma REST è ciò che usano la maggior parte dei servizi e dei backend creati con l'AI.

Un esempio pratico: la conferma di una prenotazione

Quando un cliente prenota un taglio di capelli in un'app di un salone, possono avvenire diverse chiamate API in uno o due secondi:

1. La pagina di prenotazione nel browser invia POST /api/bookings con il servizio, l'orario e i dati del cliente al tuo backend.
2. Il tuo backend verifica che lo slot sia libero, salva la prenotazione nel database e restituisce 201 Created.
3. Il tuo backend chiama l'API di un fornitore di email con la sua chiave segreta: “invia questa conferma a lena@example.com”.
4. Se c'è un acconto, il tuo backend chiede all'API del fornitore di pagamenti di creare una sessione di checkout e invia lì il cliente.
5. Più tardi, il fornitore di pagamenti chiama la tua app per dire che il pagamento è andato a buon fine. Quella chiamata inversa è un webhook.

I primi due passaggi sono la tua API tra frontend e backend. I passaggi 3–5 sono API di terze parti.

Termini comuni spiegati

Errori comuni e false convinzioni

• Mettere le chiavi segrete nel frontend. Tutto ciò che è nel codice eseguito nel browser può essere visto da chiunque visiti il sito. Le chiavi segrete devono restare sul server, nelle variabili d'ambiente o nei segreti.
• Incollare le chiavi in chat. La cronologia della chat potrebbe essere conservata. Usa invece la funzione segreti del tuo builder, e ruota qualsiasi chiave che hai esposto.
• Dare per scontato che un'API sia gratuita. Molte API addebitano per richiesta o per unità di utilizzo — le API dei modelli AI si pagano a token. Controlla i prezzi e imposta limiti di spesa. Vedi come usare le API degli LLM.
• Non gestire i fallimenti. I servizi esterni vanno giù, scadono e raggiungono i limiti. Chiedi messaggi di errore sensati e nuovi tentativi.
• Fidarsi del browser. La tua API deve verificare da sola i permessi. Nascondere un pulsante non impedisce a qualcuno di chiamare direttamente l'endpoint.
• Usare chiavi live durante i test. Usa le chiavi della modalità test finché non sei pronto al lancio.

Cosa chiedere al tuo AI builder

• “Quali API esterne usa questa app, e quanto costa ciascuna?”
• “Chiama l'API dei pagamenti solo dal server. Leggi la chiave da una variabile d'ambiente.”
• “Elenca ogni endpoint della nostra API, cosa fa e chi è autorizzato a chiamarlo.”
• “Verifica sul server che l'utente connesso sia il proprietario della prenotazione prima di aggiornarla o eliminarla.”
• “Se l'API delle email fallisce, salva comunque la prenotazione e registra l'errore.”
• “Usa per ora la modalità test del fornitore.”

Le API in Mythex

Mythex può costruire una tua API — come parte di una web app, o come backend separato in Node, Python (FastAPI), C# o Java che gira accanto al frontend — e scrivere il codice che chiama i servizi esterni. Inserisci le loro chiavi come segreti del progetto invece che in chat, e sono disponibili alla tua app nell'anteprima e una volta pubblicata. La documentazione contiene ricette per integrare qualsiasi API e costruire un backend API REST.

Domande