API REST spiegate ai non sviluppatori

Che cos'è un'API REST?

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

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

È qui che entrano in gioco le API. Un'API consente a due sistemi software di comunicare seguendo un insieme definito di regole. Un'API REST è uno dei modi più comuni per farlo sul 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 potrebbe rispondere:

“Prenotazione creata.”

REST significa Representational State Transfer. Non è necessario ricordare il significato dell'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, aggiornarle 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 è questo:

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

La risposta potrebbe includere temperatura, condizioni meteorologiche 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 prende la richiesta e porta la risposta.
• La cucina è il servizio che svolge il lavoro.

L'API svolge sia il ruolo del menu sia quello del cameriere. Ti indica che cosa puoi chiedere, come formulare la richiesta e quale 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 il funzionamento interno di un servizio per utilizzarne l'API.

Come funziona una richiesta a un'API REST?

Ogni richiesta API contiene alcuni elementi essenziali.

Endpoint: dove inviare la richiesta

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

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

Questo potrebbe rappresentare il prodotto con ID 42. Endpoint diversi possono rappresentare un insieme di risorse, un singolo elemento o un'operazione specifica.

Metodo HTTP: che cosa vuoi fare

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

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

Per esempio, su una piattaforma di prenotazione:

GET /bookings

potrebbe recuperare le prenotazioni, mentre:

POST /bookings

potrebbe crearne una nuova. Si tratta di convenzioni molto diffuse, ma non di una garanzia assoluta. La documentazione dell'API rimane sempre il riferimento definitivo.

Header e body: informazioni aggiuntive

Gli header contengono informazioni di supporto per la richiesta, come il formato dei dati o le credenziali utilizzate per l'autenticazione. Il body, invece, contiene i dati necessari per eseguire l'operazione. Per esempio, se vuoi creare una prenotazione, 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 facile da leggere sia per le persone sia per i software.

Che cosa succede quando arriva la risposta?

Dopo aver ricevuto la richiesta, il servizio la elabora e restituisce una risposta. In genere, la risposta contiene i dati richiesti o il risultato dell'operazione, insieme a un codice di stato HTTP che indica che cosa è successo. I codici più comuni rientrano in tre categorie principali.

200–299: è andato tutto bene

La richiesta è stata gestita correttamente. Per esempio:

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

400–499: c'è un problema con la richiesta

Di solito, il problema riguarda la richiesta stessa 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 dispone dei permessi necessari;
• 404 Not Found → la risorsa richiesta non esiste.

500–599: problema lato server

Il servizio incaricato di gestire la richiesta ha riscontrato un problema. Per gli utenti, però, un codice come 409 o 500 significa ben poco. Una buona applicazione trasforma quindi l'errore tecnico in un messaggio chiaro:

“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?

Queste tecnologie e questi concetti sono collegati, ma hanno scopi differenti.

API REST e database

Un database memorizza le informazioni. Un'API, invece, definisce il modo in cui altri sistemi possono interagire con tali informazioni. Per esempio, un database potrebbe contenere:

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

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

API REST e webhook

API e webhook operano in direzioni diverse. Con una normale richiesta API, la tua applicazione chiede qualcosa:

“Il pagamento è andato a buon fine?”

Con un webhook, un altro servizio comunica in modo proattivo alla tua applicazione che è successo qualcosa:

“Il pagamento è appena stato completato con successo.”

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

REST e GraphQL

REST e GraphQL sono due approcci diversi alla comunicazione tra applicazioni. Con REST si lavora generalmente con più endpoint che rappresentano risorse differenti. GraphQL utilizza invece un'interfaccia di interrogazione attraverso la quale il client può specificare esattamente quali dati vuole ricevere. GraphQL può essere particolarmente utile quando i requisiti relativi ai dati sono complessi e il client necessita di un maggiore controllo sulla risposta. REST, invece, è molto diffuso e spesso più facile da comprendere. Nessuno dei due approcci, però, è sempre migliore dell'altro. La scelta giusta dipende dall'architettura del servizio, dai requisiti del prodotto, dal team e dal tipo di client che lo utilizzerà.

Autenticazione e autorizzazione non sono la stessa cosa

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

“Chi sei?”

Autorizzazione:

“Che cosa puoi fare?”

Immagina una piattaforma con clienti e amministratori. L'accesso verifica che tu sia davvero un determinato utente. Questo, però, non significa automaticamente che tu possa vedere tutti i dati dell'app. Un cliente potrebbe vedere le proprie prenotazioni. Un amministratore potrebbe vedere le prenotazioni di tutti i clienti. Il tipo di informazione usato per identificare l'utente è lo stesso, ma i permessi sono diversi.

E le chiavi API?

Una chiave API identifica spesso l'applicazione o il servizio che effettua una richiesta. Una sessione autenticata, invece, può identificare l'utente che ha eseguito l'accesso. Nessuna delle due deve essere considerata un lasciapassare universale.

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

“Aggiungi l'accesso 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 anche una struttura di base per profili e ruoli. Ciò significa che non devi creare manualmente una tabella delle password né implementare da zero la logica di autenticazione.

Dove devono essere conservate le chiavi API?

Le credenziali private sono un altro aspetto fondamentale. Una chiave API segreta non deve essere inserita nel frontend, pubblicata su GitHub o memorizzata in un campo accessibile agli utenti. Quando un progetto Coderblock richiede un segreto, l'agente può raccoglierlo tramite una richiesta sicura di variabili d'ambiente. Il valore viene archiviato nell'area dei segreti lato server del progetto e non viene aggiunto al codice frontend né alla conversazione.

Come progettare una funzionalità che utilizza un'API

Quando crei un'app con un builder basato sull'AI, non devi partire dalla tecnologia. Parti dal risultato che vuoi offrire all'utente. “Mostra ai clienti lo stato di consegna del loro ordine” è più utile di:

“Aggiungi un'API.”

A partire da questo obiettivo, puoi definire ciò che serve.

1. Individua 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 fonte attendibile e univoca.

2. Consulta la documentazione

Prima di integrare un servizio, verifica:

• gli endpoint disponibili;
• i metodi di autenticazione;
• gli ambienti di test;
• i limiti di utilizzo;
• i formati di richiesta e risposta;
• la disponibilità dei webhook.

3. Pianifica la gestione degli errori

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

4. Convalida i dati in entrata e in uscita

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

5. Limita i permessi

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

6. Proteggi i segreti

Le credenziali private devono rimanere lato server. Il browser non deve mai ricevere una chiave API in grado di eseguire operazioni riservate.

7. Esegui i test prima della messa in produzione

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

8. Evita le richieste non necessarie

Non tutte le informazioni devono essere richieste ogni volta che viene caricata una pagina. Quando i dati lo consentono, la cache può ridurre i tempi di risposta, il numero di richieste e i costi dell'integrazione.

Lavorare con le API in Coderblock

Con Coderblock, le API entrano a far parte dello stesso flusso di lavoro conversazionale utilizzato per creare 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 desiderato. Per esempio:

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

Una richiesta di questo tipo comunica non soltanto quale tecnologia utilizzare, ma soprattutto che cosa deve accadere nell'app. L'agente può occuparsi dell'implementazione sottostante mentre tu controlli il risultato nell'anteprima live su coderblock.dev e continui a perfezionarlo tramite chat.

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

Non devi essere uno sviluppatore per comprendere il concetto di API REST. Conoscerne le basi, però, cambia il modo in cui progetti un'app. Ti aiuta a capire perché un'integrazione con Stripe è diversa dal collegamento a un database, perché un webhook è diverso da una normale richiesta API e perché una chiave API non deve mai essere esposta nel frontend. Soprattutto, ti aiuta a scrivere prompt migliori per l'AI.

Invece di chiedere semplicemente:

“Aggiungi un'API.”

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

Ma più chiaramente riesci a descrivere il comportamento che desideri, maggiore sarà il controllo sul prodotto che stai creando.