Una REST API (Representational State Transfer) è il tipo di interfaccia web più diffuso al mondo per la comunicazione tra sistemi software. Basata su HTTP, definisce principi architetturali chiari: URL come identificatori di risorse, metodi HTTP semantici, risposte JSON, assenza di stato tra richieste. È lo standard che consente ai chatbot di integrarsi con CRM, ERP, calendari e qualsiasi sistema moderno.
Cos'è una REST API?
REST non è un protocollo o uno standard formale, ma un stile architetturaledefinito nel 2000 da Roy Fielding nella sua tesi di dottorato. Descrive come progettare sistemi distribuiti scalabili e performanti usando HTTP come protocollo di comunicazione. Un'API che segue i principi REST è chiamata "RESTful".
La popolarità delle REST API è dovuta alla loro semplicità: usano HTTP (universalmente supportato), JSON come formato dati (leggibile da qualsiasi linguaggio di programmazione), e seguono convenzioni intuitive che un qualsiasi sviluppatore può capire rapidamente. Per questo motivo, praticamente ogni servizio moderno, da Twitter/X a Stripe, da Salesforce a Google Maps, espone le proprie funzionalità tramite REST API.
Nel contesto del customer support automatizzato, le REST API sono il collante che permette al chatbot di essere più di un bot di risposte statiche: integrandosi con i sistemi aziendali tramite API, il bot può recuperare dati in tempo reale, eseguire azioni concrete (creare prenotazioni, aprire ticket, aggiornare record) e offrire un'esperienza veramente utile.
I 6 Principi REST
1. Stateless
Il server non mantiene stato tra le richieste. Ogni richiesta deve contenere tutte le informazioni necessarie per essere elaborata (incluse le credenziali di autenticazione). Questo rende il sistema altamente scalabile: qualsiasi server del cluster può gestire qualsiasi richiesta senza coordinazione.
2. Interfaccia Uniforme
Risorse identificate da URL, operazioni tramite metodi HTTP standard, risposte in formato uniforme (JSON). La standardizzazione riduce la curva di apprendimento: uno sviluppatore che conosce una REST API può capire rapidamente qualsiasi altra.
3. Client-Server
Separazione netta tra client (chi consuma l'API: chatbot, frontend, script) e server (chi espone le risorse). Il client non sa niente dell'implementazione interna del server, il server non sa niente dell'interfaccia del client. Evoluzione indipendente.
4. Cacheable
Le risposte possono essere marcate come cacheable o no. Il client (o un proxy intermedio) può mettere in cache le risposte per riutilizzarle nelle richieste successive, riducendo latenza e carico server. GET /products restituisce la stessa lista per 5 minuti: cacheabile.
5. Layered System
Il client non sa se comunica direttamente con il server finale o con intermediari (load balancer, CDN, API gateway, cache). Questo permette architetture complesse e scalabili trasparenti al client.
6. (Opzionale) Code on Demand
Il server può inviare codice eseguibile al client (es. JavaScript). Raro nelle REST API standard, più comune nelle architetture web tradizionali. L'unico principio opzionale dei sei definiti da Fielding.
Metodi HTTP e Design degli Endpoint
GET: Lettura
Recupera dati senza modificarli (operazione "safe" e "idempotente"). I parametri di filtro vanno nella query string. Le risposte GET possono essere messe in cache.
POST: Creazione
Crea una nuova risorsa. Il payload JSON va nel body della richiesta. Non è idempotente: chiamare POST due volte crea due risorse distinte. Risposta tipica: 201 Created con la risorsa creata e l'URL nel header Location.
PUT / PATCH: Aggiornamento
PUT sostituisce completamente la risorsa con il payload fornito (tutti i campi obbligatori). PATCH aggiorna solo i campi specificati nel payload (aggiornamento parziale). PATCH è più efficiente per modifiche parziali, PUT garantisce lo stato finale completo della risorsa.
DELETE: Eliminazione
Elimina la risorsa specificata. È idempotente: eliminare la stessa risorsa più volte ha lo stesso effetto (risorsa non esiste). Risposta tipica: 204 No Content (eliminazione riuscita, nessun body) o 404 Not Found (risorsa già eliminata o mai esistita).
Versionamento e Design URL
Versionamento nell'URL
Il metodo più diffuso è includere la versione nel path dell'URL. Permette di mantenere versioni precedenti attive durante la transizione e di deprecarle gradualmente:
Alternative: versione nell'header (Accept: application/vnd.api+json;version=2) o nel subdominio (v2.api.esempio.it). L'URL è il metodo più visibile e semplice.
Convenzioni URL RESTful
/api/v1/users | plurale, minuscolo, trattini per separare parole/api/v1/getUsers | no verbi negli URL (il verbo è il metodo HTTP)/api/v1/users/123/orders | risorse annidate per relazioni/api/v1/User/123/GetOrders | no camelCase o PascalCase negli URL?page=2&limit=20 | paginazione tramite query paramsDocumentazione OpenAPI / Swagger
Cos'è la Specifica OpenAPI
OpenAPI (ex Swagger) è lo standard per descrivere REST API in modo machine-readable (YAML o JSON). Da questa specifica si genera automaticamente: documentazione interattiva (Swagger UI) dove testare gli endpoint dal browser, client SDK in qualsiasi linguaggio, server stub per il testing, e validazione automatica delle richieste.
Cosa Include una Buona Documentazione API
- URL base, versione e ambiente (production/staging/development)
- Autenticazione richiesta (API key, OAuth 2.0, JWT) con esempi
- Ogni endpoint: metodo HTTP, URL, parametri con tipi e validazioni
- Esempi realistici di request body e response body in JSON
- Tutti i possibili codici di errore con descrizione e soluzione suggerita
- Rate limiting (quante chiamate al minuto/giorno)
- Changelog delle versioni e deprecation notice
Strumenti per Testare REST API
Prima di integrare un'API nel codice, conviene testarla manualmente con strumenti dedicati:
- Postman: tool desktop per costruire, testare e documentare richieste API
- Insomnia: alternativa open source a Postman, leggera e veloce
- curl: comando da terminale, presente su tutti i sistemi Unix/Linux/Mac
- Swagger UI: interfaccia web generata dalla specifica OpenAPI, testabile dal browser
- HTTPie: alternativa a curl con output JSON formattato
Domande Frequenti
Cos'è una REST API?
Una REST API è un'interfaccia di comunicazione tra sistemi software basata su HTTP. Segue principi architetturali chiari: ogni risorsa ha un URL univoco, le operazioni usano metodi HTTP semantici (GET per leggere, POST per creare, PUT/PATCH per aggiornare, DELETE per eliminare), le risposte sono in JSON, e il server non mantiene stato tra le richieste. È il tipo di API più diffuso al mondo per la sua semplicità e standardizzazione.
Differenza GET vs POST?
GET legge dati senza modificarli: i parametri vanno nell'URL, le risposte sono cacheable, e ripetere la stessa richiesta GET ha sempre lo stesso effetto. POST crea nuovi dati: il payload va nel body della richiesta, non è cacheable, e ripetere la stessa chiamata POST crea risorse duplicate. In sintesi: GET è "dammi i dati", POST è "crea questo nuovo dato".
Come si documenta una REST API?
Lo standard è OpenAPI (ex Swagger): una specifica YAML o JSON che descrive ogni endpoint, parametri, tipi di dati, autenticazione, esempi e codici di errore. Da questa specifica si genera automaticamente Swagger UI, un'interfaccia interattiva dove gli sviluppatori possono testare gli endpoint dal browser senza scrivere codice. Postman è l'alternativa più usata per test e documentazione collaborativa.
Termini Correlati
Implementa REST API nella Tua Azienda
Scopri come V Support può aiutarti a sfruttare l'AI per il tuo customer service. Demo gratuita di 30 minuti.