GraphQL vs REST: guida completa

Le API sono la spina dorsale delle applicazioni web e mobile moderne. Quasi ogni app sul tuo telefono e ogni sito che visiti usa API per recuperare e gestire i dati mostrati sullo schermo. 

REST e GraphQL sono due dei paradigmi di progettazione API più comuni. Questa guida esplora le differenze fondamentali, i benefici e i casi d’uso ideali per entrambi, così potrai scegliere l’approccio che preferisci per il tuo progetto o i tuoi progetti.

Aspetta, cos’è un’API?
Se sei completamente nuovo al concetto di API (Application Programming Interface), prendi in considerazione il nostro corso Streamlined Data Ingestion with Pandas. Ti insegnerà come le applicazioni possono sfruttare le API per comunicare con altri programmi – e viceversa – senza che nessuna delle due parti conosca i dettagli del funzionamento interno dell’altra. Il corso ti renderà esperto delle regole e dei protocolli che le applicazioni usano per richiedere e scambiare informazioni.

Che cos’è REST?

REST (Representational State Transfer) è uno stile architetturale usato per sviluppare servizi web dall’inizio degli anni 2000. Definisce una serie di vincoli e principi per creare API scalabili e stateless. Le API REST (dette anche RESTful) sono progettate per essere leggere e possono essere usate in qualsiasi linguaggio o piattaforma che supporti HTTP.

Se sei alle prime armi con le API REST, ti consiglierei di abituarti a interagirci prima di svilupparne una tua. Ti aiuterà a capire come funzionano e quali sono le best practice. Dai un’occhiata a Intermediate Importing Data in Python o Intermediate Importing Data in R per iniziare. Entrambi i corsi hanno capitoli sulle richieste HTTP, sullo scraping del web e altre cose divertenti. 

Concetti chiave delle API REST

Proviamo a capire i concetti di REST. 

Statelessness

Ogni interazione tra client e server è indipendente. Il server non memorizza dati di sessione relativi al client tra una richiesta e l’altra, il che significa che ogni richiesta da un client a un server deve contenere tutte le informazioni necessarie per comprendere ed elaborare quella richiesta.

Basato su risorse

Ogni dato o funzionalità è trattato come una risorsa che può essere identificata e manipolata tramite un identificatore univoco, tipicamente un URI (Uniform Resource Identifier). 

Per esempio, in un’applicazione e-commerce, le risorse possono includere clienti, prodotti, ordini, ecc. Ogni risorsa è identificata da un URI univoco che funge da indirizzo dove la risorsa è accessibile. Per esempio:

• /products può riferirsi alla collezione di tutti i prodotti.

• /products/123 può riferirsi a un prodotto specifico con ID 123.

Metodi HTTP

Le API RESTful usano tipicamente i metodi HTTP standard per eseguire operazioni sulle risorse:

• GET: recupera dati da un server (ad es., ottieni un elenco di prodotti).

• POST: invia dati al server (ad es., crea un nuovo prodotto).

• PUT: aggiorna una risorsa esistente (ad es., modifica i dettagli di un prodotto).

• DELETE: rimuove una risorsa (ad es., elimina un prodotto).

Una richiesta GET standard potrebbe essere così:

Esempio di richiesta e risposta REST. Immagine dell’autore.

Le API REST usano anche i codici di stato HTTP standard per comunicare errori, successi e altre risposte. E sì, lo stato 418 I’m a teapot esiste davvero!

Formati dei dati

Un’API RESTful può usare diversi formati per rappresentare e scambiare dati, inclusi JSON, XML, HTML, testo semplice, YAML e CSV.

Che cos’è GraphQL?

GraphQL è un linguaggio di query e un runtime open source per API che consente ai client di richiedere esattamente i dati di cui hanno bisogno, e niente di più. È stato sviluppato internamente da Meta (precedentemente Facebook) nel 2012 per ottimizzare il recupero dei dati nelle loro app mobile ed è stato rilasciato al pubblico nel 2015.

Concetti chiave delle API GraphQL

Diamo un’occhiata alle idee principali di GraphQL.

Query specifiche del client

In GraphQL, i client definiscono la struttura della risposta specificando i campi di cui hanno bisogno nelle loro query. Ciò significa che il client può richiedere solo i dati specifici necessari, evitando over-fetching (ricezione di troppi dati) e under-fetching (ricezione di dati insufficienti).

In GraphQL, una query per ottenere i dettagli di un utente potrebbe essere così:

Esempio di richiesta e risposta GraphQL. Immagine dell’autore.

Query vs mutation

Mentre le query sono usate per leggere i dati, le mutation sono usate per scrivere o modificare i dati. Le mutation in GraphQL sono analoghe alle operazioni POST, PUT e DELETE in REST.

Endpoint unico

A differenza delle API REST, che possono avere più endpoint per risorse diverse, un’API GraphQL espone tipicamente un unico endpoint. Questo endpoint gestisce tutte le query e le mutation, semplificando l’interazione dei client con l’API.

Schema fortemente tipizzato

Le API GraphQL sono definite da uno schema, ovvero una definizione fortemente tipizzata dei modelli di dati disponibili e delle relazioni tra di essi. Questo schema funge da contratto tra client e server, assicurando che i dati restituiti corrispondano alla richiesta del client e siano del tipo previsto.

Introspection

Lo schema GraphQL è autodocumentante. I client possono usare la funzionalità di introspection per interrogare lo schema stesso e scoprire i tipi, le query, le mutation e le subscription disponibili, facilitando l’esplorazione e la comprensione dell’API.

Dati in tempo reale

GraphQL supporta aggiornamenti dei dati in tempo reale tramite le subscription. Le subscription consentono ai client di ricevere aggiornamenti ogni volta che cambiano i dati di loro interesse, utile per applicazioni real-time come chat o feed live.

Differenze chiave tra GraphQL e REST

La tabella seguente riassume le principali differenze tra API GraphQL e REST.

Come per molte cose nella vita, ogni soluzione ha i suoi pro e contro.

Come scegliere tra GraphQL e REST

La scelta tra REST e GraphQL dipenderà interamente dalle esigenze del tuo progetto. Probabilmente hai già un’idea dalla sezione precedente, ma come regola generale, ti conviene usare REST quando hai:

• Modelli di dati semplici
• Applicazioni che richiedono caching esteso.
• Team abituati alle convenzioni REST.
• Necessità di risposte prevedibili e standardizzate.

E usa GraphQL quando ti trovi a gestire:

• Modelli di dati complessi con relazioni annidate.
• Applicazioni che necessitano di query flessibili e dinamiche.
• Iterazioni rapide e minori modifiche al backend.
• Aggiornamenti in tempo reale.

REST e GraphQL possono anche essere usati insieme in soluzioni ibride, così il tuo progetto può beneficiare di endpoint REST semplici e ben definiti ma anche della flessibilità di GraphQL per recuperi dati più complessi. Per esempio, in un’app e-commerce potresti usare REST per autenticazione e registrazione utenti, per beneficiare di pratiche di sicurezza standard come Oauth, e usare GraphQL per ottenere informazioni più annidate e complesse come dettagli prodotto, categorie e recensioni degli utenti.

Conclusione

Insomma: sia GraphQL sia REST hanno punti di forza e debolezze e sono adatti a scenari diversi. La scelta tra i due dovrebbe essere guidata dai requisiti del tuo progetto e dalla complessità dei dati. 

Detto ciò, entrambi gli strumenti sono davvero divertenti da usare e possono insegnarti molto sui dati, quindi se ne hai l’opportunità ti consiglierei di provarli!

E, se dopo questa lettura sai quale strumento vuoi usare, sei pronto per lo step successivo! Dai un’occhiata al nostro post Mastering API Design: Essential Strategies for Developing High-Performance APIs per imparare a progettare le tue API.