Che cos'è un'API REST?

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

Un ciclo CRUD completo in HTTP grezzo

Tutto lo stile in quattro richieste – è questo che ogni framework e ogni SDK finisce per inviare:

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 / 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 — 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

// 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

// 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<ParseObject>("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, 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, condensata:

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 completa ha una voce a sé.

Codici di stato: che cosa restituire e quando

È 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 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).

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

Il confronto con GraphQL 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, la via più rapida dallo schema a un’API funzionante.

Conviene usare REST? Matrice decisionale

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; 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.