Nel precedente articolo abbiamo tracciato una panoramica generale di cosa siano le REST API e cosa sia GraphQL, ripercorrendo le loro origini, i principi su cui si basano e le differenze filosofiche alla base dei due approcci. Abbiamo visto come REST, nato come modello architetturale all’inizio degli anni 2000, si sia imposto come standard di fatto per la comunicazione tra sistemi distribuiti, e come GraphQL, sviluppato da Facebook nel 2012 e reso pubblico nel 2015, abbia introdotto un paradigma radicalmente diverso nella gestione e nel recupero dei dati.

Ora, però, è arrivato il momento di passare dalla teoria alla pratica. Non ci limiteremo più a dire “REST fa così” e “GraphQL fa cosà”: in questo approfondimento entreremo nel dettaglio tecnico, mettendo a confronto in modo diretto i due approcci, analizzando le loro differenze operative e valutando in quali scenari ciascuno di essi esprime al meglio il proprio potenziale.

La scelta tra REST e GraphQL, infatti, non è un semplice esercizio accademico o una questione di preferenze personali. È una decisione che può avere conseguenze molto concrete sulla vita di un progetto: dalla velocità di sviluppo iniziale alla facilità di manutenzione nel lungo periodo, dal carico sul server alla complessità del frontend, fino ad arrivare a questioni delicate come la sicurezza e la scalabilità. Scegliere “a sensazione” o perché “è la moda del momento” rischia di portare a soluzioni sbilanciate, in cui l’architettura scelta non si adatta davvero alle esigenze del prodotto, del team e dell’infrastruttura.

In altre parole, la domanda non è tanto “Quale tecnologia è migliore?” — perché la risposta universale semplicemente non esiste — ma piuttosto “Quale tecnologia è più adatta al contesto in cui sto lavorando?”. Per rispondere in modo informato a questa domanda, dobbiamo analizzare non solo i principi, ma anche le differenze tecniche, i punti di forza, i limiti e gli impatti concreti di ciascun approccio.

Questo articolo è quindi strutturato per accompagnarti, passo dopo passo, attraverso i principali aspetti che differenziano REST e GraphQL: dalla gestione degli endpoint al formato delle richieste, dalla tipizzazione alla strategia di versionamento, fino alle implicazioni sul lavoro del frontend e del backend. Approfondiremo anche temi spesso sottovalutati come le performance, la sicurezza e le possibilità di caching, per arrivare poi a una sintesi pratica dei vantaggi e svantaggi di entrambi.

Alla fine di questa lettura, l’obiettivo è che tu possa avere un quadro chiaro e bilanciato, capace di guidarti nella scelta tecnologica non in astratto, ma in base al tuo progetto specifico. Iniziamo.

Differenze tecniche fondamentali

Quando si passa dalla teoria alla pratica, la prima cosa che emerge è che REST e GraphQL non sono semplicemente due modi diversi di chiedere dati: sono due approcci che cambiano radicalmente il modo in cui frontend e backend dialogano. Le differenze tecniche che vedremo tra poco non sono meri dettagli implementativi, ma vere e proprie scelte architetturali che influenzano performance, manutenibilità e flessibilità di un progetto.

Numero di endpoint vs endpoint unico

Nel mondo REST, ogni risorsa (e talvolta ogni operazione su quella risorsa) ha un suo endpoint dedicato. Se vogliamo ottenere la lista degli articoli di un blog, interrogheremo ad esempio:

GET /api/posts

Se invece vogliamo il dettaglio di un singolo articolo, l’endpoint sarà un altro:

GET /api/posts/42

E così via, con operazioni diverse (POST, PUT, DELETE) e risorse diverse (utenti, commenti, categorie) che generano una vera e propria “mappa” di endpoint. Questo approccio ha il vantaggio di essere molto chiaro e prevedibile: ogni URL corrisponde a qualcosa di preciso e documentabile.

GraphQL ribalta completamente il concetto. Qui non esiste una collezione di endpoint: ce n’è uno solo (ad esempio /graphql), e tutte le richieste passano da lì. La differenza sta nel fatto che è il client a decidere cosa ottenere, scrivendo query che specificano esattamente i campi desiderati. Per esempio, una query GraphQL per ottenere solo il titolo e la data di pubblicazione di un articolo potrebbe essere:

query {
  post(id: 42) {
    title
    publishedAt
  }
}

Risultato: un solo endpoint, infinite possibilità di combinare i dati. Questo semplifica enormemente il routing, ma richiede al server un livello di logica in più per interpretare e risolvere le query dinamiche.

Formato delle richieste e risposte

Le REST API, nella stragrande maggioranza dei casi moderni, scambiano dati in formato JSON. La struttura è decisa dal server e tutti i client ricevono lo stesso payload, anche se non hanno bisogno di tutti quei campi.

Esempio di risposta REST per un utente:

{
  "id": 42,
  "name": "Mario Rossi",
  "email": "mario@example.com",
  "avatar_url": "https://example.com/avatar.jpg",
  "created_at": "2025-05-10"
}

Se il frontend avesse bisogno solo del nome e dell’email, riceverebbe comunque tutti gli altri dati, con relativo peso in termini di rete e parsing.

GraphQL, invece, consente al client di definire il formato della risposta all’interno della query. Se ci servono solo name ed email, il server restituirà esattamente e soltanto quei campi, riducendo il payload al minimo:

query {
  user(id: 42) {
    name
    email
  }
}

E risposta:

{
  "data": {
    "user": {
      "name": "Mario Rossi",
      "email": "mario@example.com"
    }
  }
}

Questo approccio migliora l’efficienza, ma richiede attenzione: query troppo “ambiziose” possono appesantire il server più di quanto accadrebbe con REST.

Tipizzazione dei dati

In GraphQL, lo schema è fortemente tipizzato. Significa che ogni campo, ogni tipo di dato e ogni operazione sono definiti in un contratto formale che il server espone e che i client possono interrogare. Questo rende possibile l’introspezione, ovvero la capacità di ottenere automaticamente la struttura dell’API, utile per tool di sviluppo e generazione automatica di codice lato client.

REST non ha un meccanismo di tipizzazione intrinseco: si basa su convenzioni e documentazione esterna (manuale o automatica tramite strumenti come Swagger/OpenAPI). Questo dà più libertà, ma lascia più spazio a incoerenze o a cambiamenti non gestiti che possono rompere la compatibilità.

Gestione del versionamento

Uno degli aspetti più delicati nella vita di un’API è gestire le modifiche senza rompere il funzionamento dei client esistenti.

REST tradizionalmente affronta il problema creando versioni multiple dell’API, spesso indicate nell’URL:

/api/v1/posts
/api/v2/posts

Questo garantisce stabilità, ma può portare a una moltiplicazione di endpoint e alla necessità di mantenere in vita più versioni contemporaneamente.

GraphQL adotta un approccio evolutivo: lo schema può essere modificato aggiungendo campi e contrassegnando come deprecated quelli obsoleti. In questo modo, i client vengono avvisati di un cambiamento imminente e possono aggiornarsi gradualmente, senza introdurre nuove versioni di endpoint.

Impatto su frontend e backend

In un’architettura REST, la logica di quali dati fornire è decisa dal backend. Il frontend riceve pacchetti di informazioni predefiniti, il che semplifica la vita ai team backend (che controllano i payload) ma può obbligare i frontend developer a fare più chiamate per comporre una singola schermata.

In GraphQL, il frontend ha molto più potere: decide esattamente cosa vuole e come vuole riceverlo, riducendo il numero di chiamate. Il rovescio della medaglia è che il backend deve essere in grado di risolvere query potenzialmente complesse e ottimizzare le prestazioni, per evitare di appesantire il database o saturare le risorse del server.

Conclusione

Abbiamo visto come REST e GraphQL differiscano sostanzialmente in aspetti tecnici come la gestione degli endpoint, il formato delle richieste, la tipizzazione dei dati, il versionamento e l’impatto su frontend e backend. Queste differenze non sono solo teoriche: influenzano concretamente come sviluppiamo e manteniamo le API. Nel prossimo articolo, ci concentreremo su aspetti fondamentali quali performance, scalabilità, sicurezza e caching, approfondendo come queste due tecnologie si comportano in contesti reali e quali sono i compromessi da considerare per ottimizzare le nostre soluzioni.

Altri articoli

PyScript: Python nel browser

Da HTML a CSV: Come Estrarre Dati con JavaScript

Design e Usabilità: Come Creare Moduli HTML5 Efficaci e Accessibili

Come utilizzare le liste di definizioni in HTML5 per creare glossari FAQ e contenuti strutturati