--- term: 'API REST' seoTitle: 'API REST: che cos''è, vincoli, metodi e codici di stato' headline: 'Che cos''è un''API REST?' slug: api-rest category: api-realtime shortDefinition: 'Un''API REST è un tipo di API che segue lo stile architetturale REST: risorse a degli URL, richieste stateless e metodi HTTP standard.' relatedTerms: - api - graphql-vs-rest - auto-generated-database-apis - crud-operations contrastsWith: - graphql-vs-rest aboutTerms: - 'REST (Representational State Transfer)' - 'RESTful API' faq: - question: 'Che cos''è un''API REST in parole semplici?' answer: 'Un modo per far parlare due applicazioni su HTTP con convenzioni che tutti già conoscono: ogni cosa (un utente, un ordine) vive a un URL, ci si agisce con un verbo standard – GET per leggere, POST per creare, PUT o PATCH per aggiornare, DELETE per rimuovere – e ogni richiesta sta in piedi da sola, portando tutto ciò che serve al server per risponderle.' - question: 'Che cosa significa REST?' answer: 'Representational State Transfer, dalla tesi di dottorato di Roy Fielding del 2000. Il nome descrive il meccanismo: il server trasferisce al client una rappresentazione dello stato di una risorsa (di solito JSON), e il client porta l''applicazione da uno stato all''altro attraverso quelle rappresentazioni.' - question: 'Qual è la differenza tra REST e RESTful?' answer: 'Nell''uso quotidiano nessuna: i termini sono interscambiabili. Per essere pedanti, REST nomina lo stile architetturale e RESTful è l''aggettivo per un''API che lo implementa. L''affermazione che circola secondo cui "RESTful segue tutte le regole e REST solo alcune" non ha fondamento nel lavoro di Fielding.' - question: 'Quali sono i sei vincoli di REST?' answer: 'Separazione client-server, assenza di stato, cacheabilità, interfaccia uniforme, sistema a livelli e – opzionalmente – codice su richiesta. L''interfaccia uniforme si scompone a sua volta in quattro regole: risorse identificate da URI, manipolazione attraverso rappresentazioni, messaggi autodescrittivi e ipermedia come motore dello stato dell''applicazione.' - question: 'Qual è la differenza tra PUT e POST?' answer: 'Idempotenza e indirizzamento. POST crea sotto una collezione – l''URL lo assegna il server, e ripetere la richiesta crea duplicati. PUT scrive una rappresentazione completa a un URL noto – ripeterlo produce lo stesso stato, ed è questo che rende sicuri i retry. È quella differenza di sicurezza, non lo stile, a rendere importante la distinzione.' - question: 'Un''API REST deve usare JSON?' answer: 'No. REST è agnostico rispetto al formato: una risorsa può essere rappresentata come JSON, XML, HTML o immagine, negoziata attraverso gli header Accept e Content-Type. JSON è semplicemente la scelta predefinita moderna, perché ogni client lo analizza a basso costo. Il vincolo riguarda le rappresentazioni, non una in particolare.' - question: 'Che cosa significa stateless in un''API REST?' answer: 'Il server non conserva memoria del client tra una richiesta e l''altra: ogni richiesta porta tutto il necessario per essere elaborata, credenziali come un bearer token comprese. Il guadagno è la scalabilità orizzontale – qualsiasi server può rispondere a qualsiasi richiesta – e il costo sono pochi byte di contesto ripetuti a ogni chiamata.' - question: 'Che cos''è HATEOAS?' answer: 'Hypermedia As The Engine Of Application State: le risposte includono i link alle azioni disponibili dopo, così i client navigano l''API come le persone navigano il web, seguendo link invece di inserire URL nel codice. È il vincolo meno implementato; la maggior parte delle API "REST" di produzione lo salta e vive serenamente al livello 2 del modello di maturità.' codeLanguages: [javascript, dart, swift, kotlin] externalAuthorities: - name: 'Fielding dissertation, Chapter 5 — Representational State Transfer' url: 'https://ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm' - name: 'RFC 9110 — HTTP Semantics' url: 'https://www.rfc-editor.org/rfc/rfc9110' - name: 'HTTP request methods — MDN Web Docs' url: 'https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Methods' - name: 'Richardson Maturity Model — Martin Fowler' url: 'https://martinfowler.com/articles/richardsonMaturityModel.html' cta: title: 'Un''API REST che non devi costruire' text: 'Ogni modello di dati su Back4app arriva automaticamente come API REST – URL di risorse, metodi e codici di stato corretti, autenticazione e permessi al confine – più gli SDK che la avvolgono in modo idiomatico su ogni piattaforma.' linkText: 'Inizia gratis' linkUrl: 'https://www.back4app.com/signup' author: 'Back4app Engineering' publishedDate: '2026-10-02' translationKey: rest-api --- **Un'API REST è un tipo di API che segue lo stile architetturale REST: risorse a degli URL, richieste stateless e metodi HTTP standard.** REST – Representational State Transfer, definito nella [tesi](https://ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm) di dottorato di Roy Fielding del 2000 – è uno stile, non un protocollo né uno standard: un insieme di vincoli che, rispettati insieme, producono API che tutto il web sa già consumare, mettere in cache e scalare. ## Punti chiave | Domanda | Risposta | | --- | --- | | Il modello | Risorse a degli URL · rappresentazioni (di solito JSON) · metodi standard | | La fonte | La tesi di Fielding del 2000, capitolo 5 – uno stile architetturale, non una spec | | I sei vincoli | Client-server · stateless · cacheabile · interfaccia uniforme · a livelli · codice su richiesta (opzionale) | | I verbi | GET · POST · PUT · PATCH · DELETE – con semantica di sicurezza e idempotenza | | La nota onesta | Gran parte delle API "REST" di produzione sono API HTTP di livello 2 – e va bene così | ## Un ciclo CRUD completo in HTTP grezzo Tutto lo stile in quattro richieste – è questo che ogni framework e ogni SDK finisce per inviare: ```text POST /v1/posts → 201 Created creare { "title": "Hello REST" } Location: /v1/posts/8fk2 GET /v1/posts/8fk2 → 200 OK leggere { "title": "Hello REST", … } PUT /v1/posts/8fk2 → 200 OK sostituire { "title": "Hello again" } (PATCH aggiornerebbe dei campi) DELETE /v1/posts/8fk2 → 204 No Content eliminare GET /v1/posts/8fk2 → 404 Not Found …e non c'è più ``` Lo stesso ciclo attraverso gli SDK che avvolgono le chiamate REST: **JavaScript:** ```javascript // JavaScript / Node.js — Back4app JS SDK // The REST semantics, wrapped: create, read, update, delete const post = new Parse.Object('Post'); post.set('title', 'Hello REST'); await post.save(); // POST /classes/Post → 201 const fetched = await new Parse.Query('Post') .get(post.id); // GET /classes/Post/:id → 200 fetched.set('title', 'Hello again'); await fetched.save(); // PUT /classes/Post/:id → 200 await fetched.destroy(); // DELETE /classes/Post/:id → 200 ``` **Flutter:** ```dart // Flutter / Dart — Back4app Flutter SDK // The REST semantics, wrapped: create, read, update, delete final post = ParseObject('Post')..set('title', 'Hello REST'); await post.save(); // POST /classes/Post → 201 await post.fetch(); // GET /classes/Post/:id → 200 post.set('title', 'Hello again'); await post.save(); // PUT /classes/Post/:id → 200 await post.delete(); // DELETE /classes/Post/:id → 200 ``` **Swift:** ```swift // iOS / Swift — Back4app Swift SDK // The REST semantics, wrapped: create, read, update, delete var post = Post() post.title = "Hello REST" let saved = try await post.save() // POST /classes/Post → 201 let fetched = try await saved.fetch() // GET /classes/Post/:id → 200 var updated = fetched updated.title = "Hello again" _ = try await updated.save() // PUT /classes/Post/:id → 200 try await updated.delete() // DELETE /classes/Post/:id → 200 ``` **Kotlin:** ```kotlin // Android / Kotlin — Back4app Android SDK // The REST semantics, wrapped: create, read, update, delete val post = ParseObject("Post") post.put("title", "Hello REST") post.save() // POST /classes/Post → 201 val fetched = ParseQuery.getQuery("Post") .get(post.objectId) // GET /classes/Post/:id → 200 fetched.put("title", "Hello again") fetched.save() // PUT /classes/Post/:id → 200 fetched.delete() // DELETE /classes/Post/:id → 200 ``` ## I sei vincoli di REST 1. **Client-server** – interfaccia e implementazione evolvono in modo indipendente; la UI non sa mai come funziona l'archiviazione. 2. **Stateless** – ogni richiesta è autonoma; il server non tiene sessione tra le chiamate, ed è questo che permette a qualsiasi replica di rispondere a qualsiasi richiesta. 3. **Cacheabile** – le risposte dichiarano la propria cacheabilità; le GET con header di cache corretti mettono al servizio dell'API l'intera infrastruttura di caching del web (browser, [CDN](/glossary/cdn-content-delivery-network/), proxy). 4. **Interfaccia uniforme** – il vincolo che *è* REST, in quattro parti: risorse identificate da URI; manipolazione attraverso rappresentazioni (si rimanda il JSON che la risorsa deve diventare); messaggi autodescrittivi (metodo più header dicono tutto il necessario per elaborare la richiesta); e ipermedia come motore dello stato dell'applicazione (le risposte linkano le azioni successive). 5. **Sistema a livelli** – i client non possono sapere se stanno parlando con l'origine, con una cache o con un gateway; gli intermediari si inseriscono liberamente. 6. **Codice su richiesta** *(opzionale)* – i server possono spedire codice eseguibile ai client; è l'unico vincolo marcato come opzionale, e quello che la maggior parte delle API ignora. ## Metodi HTTP: sicurezza, idempotenza, CRUD La tabella che manca in quasi ogni pagina ben posizionata – la semantica dell'[RFC 9110](https://www.rfc-editor.org/rfc/rfc9110), condensata: | Metodo | Ruolo CRUD | Sicuro? | Idempotente? | Retry alla cieca? | | --- | --- | --- | --- | --- | | GET | Lettura | Sì | Sì | Sì | | POST | Creazione | No | **No** | No – può duplicare | | PUT | Sostituzione | No | Sì | Sì – stesso risultato | | PATCH | Aggiornamento parziale | No | Non garantita | Dipende dal design della patch | | DELETE | Rimozione | No | Sì | Sì – resta eliminata | *Sicuro* significa che la richiesta non cambia nulla; *idempotente* significa che ripeterla non cambia nulla di più. Non sono curiosità: sono la politica di retry. Un timeout di rete su una PUT si può ripetere senza timore, lo stesso timeout su una POST richiede una chiave di idempotenza o un controllo sui duplicati. La [mappatura CRUD](/glossary/it/operazioni-crud/) completa ha una voce a sé. ## Codici di stato: che cosa restituire e quando | Situazione | Restituire | | --- | --- | | Lettura riuscita | 200 OK | | Risorsa creata | 201 Created + header `Location` | | Eliminata; nulla da dire | 204 No Content | | Richiesta malformata | 400 Bad Request | | Credenziali assenti o non valide | 401 Unauthorized | | Autenticato ma non autorizzato | 403 Forbidden | | Risorsa inesistente | 404 Not Found | | Oltre il rate limit | 429 Too Many Requests ([dettagli](/glossary/it/rate-limiting-api/)) | | Guasto del server | 500 Internal Server Error | È nelle distinzioni fra 401 e 403 e fra 200, 201 e 204 che si vede la cura artigianale di un'API: codici precisi rendono i client diagnosticabili con la sola riga di stato. ## Quell'API è davvero REST? La scala di maturità La sezione onesta che le spiegazioni commerciali omettono. Il [Richardson Maturity Model](https://martinfowler.com/articles/richardsonMaturityModel.html) assegna un voto alle API HTTP: livello 0 (un URL, un verbo, RPC travestito), livello 1 (risorse a degli URL), livello 2 (metodi e codici di stato corretti), livello 3 (ipermedia, cioè HATEOAS). ```mermaid flowchart TB accTitle: Richardson Maturity Model per le API REST accDescr: Quattro livelli, dal livello zero in cui HTTP è solo un tunnel, passando per le risorse, poi i verbi HTTP e i codici di stato, fino al livello tre con i controlli ipermediali; la maggior parte delle API di produzione si ferma al livello due. L0["Livello 0 – un solo endpoint, POST per tutto (RPC travestito)"] --> L1["Livello 1 – risorse: /posts/8fk2"] L1 --> L2["Livello 2 – verbi + codici di stato ← qui vive la maggior parte delle API di produzione"] L2 --> L3["Livello 3 – ipermedia: le risposte linkano le azioni successive (HATEOAS)"] ``` Per l'insistenza dello stesso Fielding, un'API senza ipermedia non è REST – ha scritto un saggio tagliente che lo dice esattamente. In pratica quasi ogni acclamata "API REST" è un'API HTTP di livello 2: risorse, verbi, codici di stato, JSON, nessun ipermedia. La cosa conta meno come purezza e più come vocabolario: conoscere la scala dice che cosa significa il termine in un annuncio di lavoro (livello 2) rispetto alla tesi (livello 3), e risparmia sia l'HATEOAS da culto del cargo sia le correzioni pedanti. ## REST vs. SOAP vs. GraphQL vs. gRPC | | REST | SOAP | GraphQL | gRPC | | --- | --- | --- | --- | --- | | Natura | Stile architetturale | Protocollo | Linguaggio di query + runtime | Framework RPC | | Sul filo | JSON su HTTP | Buste XML | JSON su HTTP (un solo endpoint) | Protobuf su HTTP/2 | | Contratto | OpenAPI (per convenzione) | WSDL (obbligatorio) | Schema (integrato) | .proto (obbligatorio) | | Cache | Nativa in HTTP – il suo superpotere | Scarsa | A livello applicativo | A livello applicativo | | Punto di forza | CRUD pubblico su risorse | Formalità enterprise e legacy | Dati annidati modellati dal client | Velocità fra servizi interni | | Debolezza | Forme fisse, [over/underfetching](/glossary/overfetching-underfetching/) | Verbosità | Complessità di cache e rate limit | Frizione nel browser | Il [confronto con GraphQL](/glossary/it/graphql-vs-rest/) ha una voce intera a sé. ## Convenzioni che rendono piacevole un'API REST Oltre ai vincoli, le convenzioni su cui i consumatori danno un voto in silenzio: **risorse al plurale** (`/posts`, non `/getPost`); **annidamento di un livello al massimo** (`/posts/8fk2/comments`, e poi stop); **paginazione su ogni collezione**, basata su cursori per profondità e stabilità, con limiti applicati; **filtri e ordinamenti come parametri di query**, non come varianti di endpoint; **versionamento** con una politica esplicita (percorso `/v1/` oppure header – va scelto uno dei due e vanno pubblicate le finestre di deprecazione); **negoziazione del contenuto** rispettata (`Accept`, `Content-Type`); ed **errori come JSON strutturato** con un codice leggibile dalle macchine, non solo prosa. Niente di tutto questo sta nella tesi; tutto questo sta nella differenza fra un'API che gli sviluppatori consigliano e una che sopportano. ## Casi d'uso tipici - **API pubbliche e per partner** – l'ubiquità di REST è la feature: ogni linguaggio, strumento e sviluppatore la parla. - **Backend di app mobile e web** – il CRUD su risorse via HTTP corrisponde al modo in cui la maggior parte delle schermate consuma davvero i dati. - **Cuciture fra microservizi** – contratti interni dove gli strumenti di HTTP (gateway, tracing, caching) si guadagnano il posto. - **Integrazioni in stile webhook** – sistemi che notificano altri sistemi con semplici chiamate HTTP che entrambe le parti già capiscono. - **API di dati generate automaticamente** – piattaforme che [espongono un database come risorse REST](/glossary/it/api-generate-automaticamente/), la via più rapida dallo schema a un'API funzionante. ## Conviene usare REST? Matrice decisionale | REST è il default giusto quando… | Conviene altro quando… | | --- | --- | | API pubblica, consumatori ignoti | Maglia interna a throughput elevato → gRPC | | Dominio CRUD a forma di risorse | I client devono modellare risposte annidate → GraphQL | | La cache HTTP può reggere il carico di lettura | Serve push bidirezionale in tempo reale → [WebSocket](/glossary/it/websockets/) / [live query](/glossary/it/live-queries-tempo-reale/) | | Contano semplicità e ampiezza degli strumenti | Sono richiesti contratti enterprise formali → SOAP | | Le schermate si mappano in modo pulito sulle risorse | Una schermata aggrega cinque servizi → endpoint composito / BFF | ## Limiti e trade-off - **Le rappresentazioni fisse non calzano a client diversi.** La coppia over/underfetching è la debolezza strutturale di REST; set di campi sparsi e parametri di espansione la mitigano, GraphQL la riprogetta. - **Nessun contratto obbligatorio.** Nulla impone una spec OpenAPI, quindi molte API REST sono documentate per tradizione orale; la disciplina è facoltativa dove gRPC e GraphQL la rendono strutturale. - **L'assenza di stato ripete il contesto.** Autenticazione e contesto del tenant viaggiano su ogni richiesta – pochi byte, ma la semantica di sessione si sposta sui token e alcuni flussi (le transazioni a più passaggi) diventano scomodi. - **La tentazione dell'N+1 per costruzione.** Il ragionamento una-risorsa-per-URL invita a [client che fanno una chiamata per elemento](/glossary/it/problema-n-plus-1/); le buone API offrono espansione e operazioni in blocco prima che i consumatori improvvisino cicli. - **La parola "REST" è ambigua.** API HTTP di livello 2 in bocca a quasi tutti, architettura ipermediale nella tesi: prima di discutere conviene capire quale dei due intende una spec, un annuncio di lavoro o chi fa la revisione. ## Le API REST su Back4app Back4app è una piattaforma open-source di Backend as a Service (BaaS) che combina database gestito, API REST e GraphQL generate automaticamente, autenticazione, archiviazione di file e funzioni serverless con Cloud Code. Qui l'API REST è generata, non costruita: ogni classe del modello di dati è immediatamente una risorsa – `POST /classes/Post` crea, `GET /classes/Post/:id` legge, con i metodi, i codici di stato e la semantica di `Location` visti nella panoramica qui sopra – dietro chiavi, token utente e permessi a livello di classe che fanno rispettare il confine. Le schede di codice mostrano lo stesso ciclo attraverso gli SDK, che sono sottili involucri idiomatici esattamente su questo HTTP; quando un'operazione esce dal CRUD, una funzione Cloud Code aggiunge un endpoint su misura in un solo file. REST di livello 2, corretto per impostazione predefinita, dallo schema all'URL nel tempo che serve a definire la classe.