API REST spiegate ai non sviluppatori

Che cos'è un'API REST?

Quando utilizzi un'app, molte delle informazioni che vedi sullo schermo arrivano da servizi esterni.

Il meteo della tua destinazione, lo stato di una spedizione, il prezzo di un prodotto, una prenotazione o il risultato di un pagamento: l'app spesso non gestisce direttamente tutti questi dati. Li richiede ad altri sistemi.

È qui che entrano in gioco le API. Un'API permette a due sistemi software di comunicare tra loro attraverso regole definite. Un'API REST è uno dei modi più comuni per farlo attraverso il web. Puoi immaginarla come una conversazione strutturata tra applicazioni:

“Dammi le informazioni su questo prodotto.”

Il servizio risponde:

“Ecco il nome, il prezzo e la disponibilità.”

Oppure:

“Crea una nuova prenotazione per questo cliente.”

E il servizio può rispondere:

“Prenotazione creata.”

REST significa Representational State Transfer. Non è necessario ricordare l'acronimo per capire come funziona. Il concetto fondamentale è più semplice: un'API REST organizza i dati in risorse — come utenti, prodotti, ordini o prenotazioni — e definisce un modo standard per leggerle, crearle, modificarle o eliminarle.

Un esempio concreto

Immagina un'app di viaggi che mostra il meteo della destinazione che stai per visitare. L'app non deve necessariamente raccogliere e aggiornare da sola tutti i dati meteorologici. Può inviare una richiesta all'API di un servizio meteo.

Il flusso è:

La tua app → richiesta API → servizio meteo → risposta → la tua app

La risposta potrebbe contenere temperatura, condizioni atmosferiche e previsioni per i giorni successivi. L'utente vede semplicemente il meteo. Dietro quella schermata, però, due sistemi stanno comunicando.

L'analogia del ristorante

Un modo semplice per capire un'API è immaginare di essere al ristorante.

• Tu sei l'applicazione che vuole qualcosa.
• Il menu descrive ciò che puoi richiedere.
• Il cameriere porta la richiesta e restituisce la risposta.
• La cucina è il servizio che esegue il lavoro.

L'API svolge il ruolo del menu e del cameriere. Ti dice cosa puoi chiedere, come devi formulare la richiesta e che tipo di risposta puoi aspettarti. Non devi sapere come funziona la cucina per ordinare un piatto. Allo stesso modo, un'app non deve necessariamente conoscere l'implementazione interna di un servizio per utilizzarne l'API.

Come funziona una richiesta API REST?

Ogni richiesta API contiene alcune informazioni fondamentali.

Endpoint: dove inviare la richiesta

L'endpoint è l'indirizzo a cui viene inviata la richiesta. Per esempio:

https://api.example.com/products/42

Potrebbe rappresentare il prodotto con ID 42. Endpoint diversi possono rappresentare una raccolta di risorse, un singolo elemento oppure una determinata operazione.

Metodo HTTP: cosa vuoi fare

Il metodo HTTP indica al servizio quale operazione vuoi eseguire. I più comuni sono:

• GET → recuperare informazioni;
• POST → creare una nuova risorsa;
• PUT o PATCH → modificare una risorsa esistente;
• DELETE → eliminare una risorsa.

Per esempio, in una piattaforma di prenotazione:

GET /bookings

potrebbe recuperare le prenotazioni, mentre:

POST /bookings

potrebbe crearne una nuova. Sono convenzioni molto diffuse, ma non rappresentano una garanzia assoluta. La documentazione dell'API rimane sempre il riferimento da seguire.

Header e body: le informazioni aggiuntive

Gli header contengono informazioni di supporto alla richiesta, come il formato dei dati o le credenziali utilizzate per l'autenticazione. Il body, invece, contiene i dati necessari per eseguire l'operazione. Se vuoi creare una prenotazione, per esempio, il body potrebbe contenere:

{
  "service": "Consultation",
  "date": "2026-09-15",
  "time": "14:00"
}

Questi dati sono spesso rappresentati in JSON, un formato molto diffuso perché strutturato e facilmente leggibile sia dalle persone sia dai software.

Cosa succede quando arriva la risposta?

Dopo aver ricevuto la richiesta, il servizio la elabora e restituisce una risposta. La risposta contiene generalmente i dati richiesti oppure il risultato dell'operazione, insieme a un codice di stato HTTP che indica cosa è successo. I codici più comuni appartengono a tre grandi categorie.

200–299: tutto ok

La richiesta è stata gestita correttamente. Per esempio:

• 200 OK → richiesta completata;
• 201 Created → nuova risorsa creata.

400–499: qualcosa non va nella richiesta

Il problema riguarda generalmente la richiesta o i permessi del client. Per esempio:

• 400 Bad Request → dati non validi;
• 401 Unauthorized → autenticazione mancante o non valida;
• 403 Forbidden → l'utente non ha i permessi necessari;
• 404 Not Found → la risorsa richiesta non esiste.

500–599: problema lato server

Il servizio che dovrebbe gestire la richiesta ha incontrato un problema. Per l'utente, però, un codice come 409 o 500 non dice molto. Una buona applicazione trasforma quindi l'errore tecnico in un messaggio comprensibile:

“Questo appuntamento non è più disponibile. Scegli un altro orario.”

è molto più utile di:

“HTTP 409 Conflict.”

API REST, database, webhook e GraphQL: qual è la differenza?

Sono tecnologie e concetti collegati, ma svolgono ruoli diversi.

API REST e database

Un database serve a memorizzare informazioni. Un'API definisce invece come altri sistemi possono interagire con quelle informazioni. Per esempio, un database potrebbe contenere:

• utenti;
• prodotti;
• ordini;
• prenotazioni.

L'API può stabilire quali di questi dati possono essere letti, creati o modificati e da chi. Questo crea un livello di controllo tra l'applicazione e i dati. Collegare direttamente un browser a un database senza adeguate protezioni potrebbe infatti esporre informazioni o operazioni che dovrebbero rimanere private. In Coderblock, l'agente può progettare e applicare lo schema di un database Postgres attraverso la conversazione. Le app web standard utilizzano un progetto Supabase dedicato con Postgres, Auth, Storage e Row Level Security. La sezione Backend permette inoltre di visualizzare tabelle, utenti autenticati, storage e funzioni.

API REST e webhook

API e webhook funzionano in direzioni diverse. Con una normale richiesta API, è la tua applicazione a chiedere qualcosa:

“Il pagamento è andato a buon fine?”

Con un webhook, è invece un altro servizio a comunicare spontaneamente alla tua applicazione che è successo qualcosa:

“Il pagamento è appena andato a buon fine.”

I webhook sono particolarmente utili per eventi che avvengono in un secondo momento, come pagamenti, aggiornamenti di spedizioni o modifiche allo stato di un ordine. Devono però essere verificati e gestiti in modo sicuro. Nel flusso Stripe gestito di Coderblock, la piattaforma può occuparsi della configurazione del webhook. In modalità BYOK, l'agente richiede in modo sicuro la chiave segreta Stripe e configura automaticamente il webhook.

REST e GraphQL

REST e GraphQL sono due approcci diversi alla comunicazione tra applicazioni. Con REST, normalmente lavori con più endpoint che rappresentano risorse diverse. GraphQL utilizza invece un'interfaccia di interrogazione attraverso la quale il client può specificare quali dati vuole ricevere. GraphQL può essere particolarmente utile quando le esigenze di dati sono complesse e il client deve avere maggiore controllo sulla risposta. REST, invece, è molto diffuso e spesso più immediato da comprendere. Non esiste però un approccio universalmente migliore. La scelta dipende dall'architettura del servizio, dalle esigenze del prodotto, dal team e dal tipo di client che dovrà utilizzarlo.

Autenticazione e autorizzazione: non sono la stessa cosa

Due concetti vengono spesso confusi: autenticazione e autorizzazione. La differenza è semplice. Autenticazione:

“Chi sei?”

Autorizzazione:

“Cosa puoi fare?”

Immagina una piattaforma con clienti e amministratori. Il login serve a verificare che tu sia davvero un determinato utente. Ma questo non significa automaticamente che tu possa vedere tutti i dati presenti nell'app. Un cliente potrebbe vedere le proprie prenotazioni. Un amministratore potrebbe vedere quelle di tutti i clienti. L'identità è la stessa informazione di base, ma i permessi sono diversi.

E le API key?

Una API key identifica spesso l'applicazione o il servizio che sta effettuando una richiesta. Una sessione autenticata, invece, può identificare l'utente che ha effettuato il login. Nessuna delle due dovrebbe essere considerata un lasciapassare universale.

I permessi devono essere definiti separatamente e applicati anche lato server o database. In Coderblock puoi chiedere direttamente in chat:

“Aggiungi il login e gli account utente.”

L'agente può configurare Supabase Auth, le pagine di registrazione e accesso, la gestione delle sessioni, le route protette e la Row Level Security collegata all'utente autenticato. Le app includono inoltre una struttura di base per profili e ruoli. Non è quindi necessario creare manualmente una tabella per le password o implementare da zero la logica di autenticazione.

Dove vanno le API key?

Le credenziali private sono un altro punto fondamentale. Una API key segreta non dovrebbe essere inserita nel frontend, pubblicata su GitHub o salvata in un campo accessibile agli utenti. Quando un progetto Coderblock richiede un segreto, l'agente può acquisirlo attraverso una richiesta sicura per le variabili d'ambiente. Il valore viene conservato nell'archivio dei segreti lato server del progetto e non viene inserito nel codice frontend o nella conversazione.

Come progettare una funzionalità che utilizza un'API

Quando costruisci un'app con un AI builder, non è necessario partire dalla tecnologia. Parti dal risultato che vuoi ottenere per l'utente. “Mostra ai clienti lo stato della consegna del loro ordine” è una richiesta più utile di:

“Aggiungi un'API.”

Da lì puoi definire ciò che serve.

1. Identifica la fonte dei dati

Quale sistema contiene le informazioni corrette? Il tuo database? Un servizio esterno? Stripe? Un sistema di gestione delle spedizioni? Deve esserci una source of truth chiara.

2. Controlla la documentazione

Prima di integrare un servizio, verifica:

• endpoint disponibili;
• modalità di autenticazione;
• ambienti di test;
• limiti di utilizzo;
• formato delle richieste e delle risposte;
• eventuale supporto ai webhook.

3. Pensa agli errori

Cosa succede se il servizio esterno è lento? E se è temporaneamente offline? E se restituisce dati incompleti? Un'app ben progettata deve avere un comportamento definito anche quando un'API non risponde come previsto.

4. Valida dati in ingresso e in uscita

Non dare per scontato che ciò che arriva da un servizio esterno sia sempre corretto. I dati devono essere validati prima di essere utilizzati o salvati.

5. Limita i permessi

Un'integrazione dovrebbe avere soltanto gli accessi di cui ha realmente bisogno. Se un servizio deve leggere i pagamenti, non è detto che debba anche poterli modificare.

6. Proteggi i segreti

Le credenziali private devono rimanere lato server. Il browser non dovrebbe ricevere una API key che permette di eseguire operazioni riservate.

7. Testa prima della produzione

Quando possibile, utilizza l'ambiente di test del servizio. Verifica non solo le operazioni riuscite, ma anche richieste rifiutate, errori, timeout, duplicati e annullamenti.

8. Evita chiamate inutili

Non tutte le informazioni devono essere richieste a ogni caricamento della pagina. Quando i dati lo consentono, la cache può ridurre i tempi di risposta, il numero di chiamate e i costi dell'integrazione.

Lavorare con le API in Coderblock

Con Coderblock, le API diventano parte dello stesso flusso conversazionale utilizzato per costruire il resto dell'app. Puoi partire da un'idea o da un template di prodotto e chiedere all'AI di creare frontend, backend e database.

Quando vuoi aggiungere un'integrazione, è utile descrivere il comportamento che vuoi ottenere. Per esempio:

“Aggiungi l'accesso agli account. Ogni cliente deve poter vedere soltanto le proprie prenotazioni. Se il servizio esterno di pianificazione non è disponibile, mostra un messaggio chiaro e permetti all'utente di riprovare.”

Una richiesta di questo tipo comunica non solo quale tecnologia utilizzare, ma soprattutto cosa deve succedere nell'app. L'agente può occuparsi dell'implementazione sottostante, mentre tu puoi verificare il risultato nella preview live su coderblock.dev e continuare a perfezionarlo attraverso la chat.

Perché conoscere le API è utile anche se non sai programmare

Non devi essere uno sviluppatore per capire il concetto di API REST. Ma conoscerne le basi cambia il modo in cui progetti un'app. Ti permette di capire perché un'integrazione con Stripe è diversa dal collegamento a un database, perché un webhook è diverso da una normale richiesta API e perché una API key non dovrebbe mai essere esposta nel frontend. Soprattutto, ti aiuta a formulare richieste migliori all'AI.

Invece di chiedere semplicemente:

“Aggiungi un'API.”

puoi descrivere cosa deve accadere, quali dati devono essere utilizzati, chi può accedervi e cosa deve succedere quando qualcosa va storto. L'AI può occuparsi di gran parte della complessità tecnica.

Ma più chiaramente sai descrivere il comportamento che vuoi ottenere, più controllo hai sul prodotto che stai costruendo.