PHP Academy · Lezione

GraphQL a confronto con REST

Capisca quando GraphQL è più adatto di REST e perché

GraphQL a confronto con REST è una lezione PHP Academy gratuita su CoddyKit. Questa è la lezione 1 di 4. Puoi leggere la lezione completa qui gratuitamente — poi esercitati direttamente nel browser con un editor di codice integrato e un tutor IA disponibile 24/7. Fa parte del percorso di apprendimento PHP Academy, e i tuoi progressi si sincronizzano tra il web e l'app CoddyKit. Il corso PHP Academy include 4 lezioni in totale.

Perché GraphQL?

Si sa già come distribuire API REST in PHP. GraphQL non sostituisce HTTP e non è una soluzione miracolosa: è un linguaggio di query e un sistema di tipi che consente al client di descrivere esattamente ciò di cui ha bisogno e di ricevere esattamente quei dati, con un solo viaggio di andata e ritorno.

In questa lezione si confrontano onestamente i due approcci: i casi in cui GraphQL offre un vantaggio concreto, quelli in cui REST rimane la scelta corretta e i costi operativi di GraphQL.

Over-fetching e under-fetching

I problemi classici di REST:

Over-fetching: GET /users/1 restituisce 40 campi quando all'interfaccia ne servono 3.
Under-fetching: per visualizzare i post di un utente e il numero di commenti di ogni post, si chiama /users/1, poi /users/1/posts e infine N endpoint per i commenti.

GraphQL riunisce tutto in un'unica richiesta dichiarativa.

query {
  user(id: 1) {
    name
    posts {
      title
      commentCount
    }
  }
}

Un endpoint, uno schema tipizzato

REST espone molti URL; GraphQL espone un endpoint (in genere POST /graphql) basato su uno schema fortemente tipizzato. Lo schema è il contratto: è introspezionabile, quindi gli strumenti (completamento automatico, documentazione, generazione del codice) sono disponibili senza lavoro aggiuntivo.

Di seguito è riportato uno schema minimo in SDL. La struttura di ogni possibile risposta è nota in anticipo.

type User {
  id: ID!
  name: String!
  posts: [Post!]!
}

type Post {
  id: ID!
  title: String!
  commentCount: Int!
}

type Query {
  user(id: ID!): User
}

La risposta rispecchia la query

Una proprietà fondamentale è che la struttura della risposta JSON è prevedibile a partire dalla query. I client non devono mai indovinare i nomi dei campi. Questo elimina un'intera categoria di problemi legati all'evoluzione delle versioni: si aggiungono campi senza interrompere i client esistenti e si rendono obsoleti i campi con @deprecated invece di introdurre URL /v2.

{
  "data": {
    "user": {
      "name": "Ada",
      "posts": [
        { "title": "On Engines", "commentCount": 12 }
      ]
    }
  }
}

Quando GraphQL supera REST

GraphQL è la scelta più adatta quando:

si servono molti client eterogenei (web, iOS, Android) con esigenze di dati diverse.
i dati formano un grafo con relazioni profonde che i client attraversano dinamicamente.
si desidera aggregare più backend dietro un unico gateway tipizzato.
l'iterazione rapida sul frontend è importante e si vogliono evitare continue modifiche agli endpoint del backend.

Dove REST è ancora vincente

Non ricorra a GraphQL automaticamente. REST è più semplice e spesso migliore quando:

È necessario il caching HTTP — le cache CDN/edge usano URL e verbi come chiavi; un singolo POST /graphql per loro è opaco.
L'API è orientata alle risorse e stabile (CRUD su poche entità).
Si fa affidamento su caricamento e download di file o streaming, per i quali multipart e intervalli di byte sono funzionalità native di REST.
I consumer sono terze parti che si aspettano la semantica REST convenzionale.

Un rapido confronto in PHP

Ecco gli stessi dati assemblati secondo l'approccio REST in PHP — si noti che il client avrebbe comunque bisogno di più chiamate, oppure dovrebbe creare manualmente un parametro embed. GraphQL sposta invece questa logica di selezione sul client.

<?php
// REST: server decides the payload shape
function userResource(int $id): array {
    return [
        'id' => $id,
        'name' => 'Ada',
        'email' => 'ada@example.com',   // over-fetched by mobile
        'createdAt' => '1815-12-10',
        'posts' => [                       // pre-embedded, all-or-nothing
            ['title' => 'On Engines', 'commentCount' => 12],
        ],
    ];
}

header('Content-Type: application/json');
echo json_encode(userResource(1), JSON_PRETTY_PRINT);

I costi aggiuntivi di GraphQL

GraphQL sposta la complessità sul server. Ora deve gestire nuove problematiche:

Query N+1 — i resolver annidati eseguono una query al DB per ogni nodo, a meno che non si faccia batching (DataLoader).
Limitazione del costo e della profondità delle query — una query annidata in profondità e costruita in modo malevolo può causare un DoS.
Il caching è più difficile; in genere si esegue il caching a livello di resolver/dati, non HTTP.
La gestione degli errori è diversa: un 200 OK può comunque contenere un array errors.

Errori: 200 con un array errors

A differenza dei codici di stato REST, per convenzione GraphQL restituisce HTTP 200 e segnala gli errori parziali nel corpo della risposta. data può essere popolato solo parzialmente, mentre errors elenca ciò che non ha funzionato. I client devono esaminare entrambi.

{
  "data": { "user": null },
  "errors": [
    {
      "message": "User not found",
      "path": ["user"],
      "extensions": { "code": "NOT_FOUND" }
    }
  ]
}

Criterio decisionale

Una regola pratica:

API pubbliche, fortemente basate sul caching, con CRUD sulle risorse → REST.
API interne/di prodotto che alimentano client diversificati e sofisticati, su dati connessi → GraphQL.
Molti backend da unificare dietro un unico contratto tipizzato → gateway GraphQL.

È comune e vantaggioso usare entrambi: REST per webhook/upload, GraphQL per il grafo di lettura dell'app.

Servire GraphQL via HTTP in PHP

Dal punto di vista operativo, un endpoint GraphQL in PHP è un'unica route che legge il corpo JSON, estrae query e variables, li esegue rispetto allo schema e restituisce { data, errors }. Rispetto alle numerose route di REST, il trasporto è uniforme: tutte le variazioni risiedono nella stringa della query inviata dal client.

<?php
// Minimal GraphQL-over-HTTP entry point
$input = json_decode(file_get_contents('php://input'), true) ?? [];
$query = $input['query'] ?? '';
$variables = $input['variables'] ?? null;

// $result = GraphQL::executeQuery($schema, $query, null, $ctx, $variables);
// header('Content-Type: application/json');
// echo json_encode($result->toArray());
var_dump(['query' => $query, 'variables' => $variables]);

Verifica rapida

Quando REST mantiene un chiaro vantaggio rispetto a GraphQL?

Riepilogo

Ha confrontato GraphQL e REST negli aspetti sostanziali:

GraphQL risolve l'overfetching e l'underfetching con un unico endpoint tipizzato e una selezione guidata dal client.
È particolarmente efficace con molti client, dati a forma di grafo e aggregazione dei backend.
REST rimane una scelta solida per API pubbliche memorizzabili nella cache, CRUD semplici, upload e consumer convenzionali.
GraphQL sposta i costi sul server: N+1, limiti sul costo delle query, caching e semantica 200-con-errori.

Prossimo: costruire concretamente uno schema con webonyx/graphql-php.

Domande Frequenti

La lezione «GraphQL a confronto con REST» è gratuita?

Sì — il testo completo di «GraphQL a confronto con REST» è gratuito qui sul web. Per esercitarvi in modo interattivo (un editor di codice integrato e un tutor IA 24/7) e sbloccare il resto del corso PHP Academy, passa a CoddyKit PRO. Il corso PHP Academy include 4 lezioni in totale.

Cosa imparerò in «GraphQL a confronto con REST»?

Capisca quando GraphQL è più adatto di REST e perché Eserciti PHP Academy con codice pratico che esegui direttamente nel browser, e un tutor IA 24/7 risponde alle tue domande mentre lavori sulla lezione.

Ho bisogno di esperienza per iniziare PHP Academy?

Non è richiesta alcuna esperienza precedente. PHP Academy su CoddyKit è strutturato per principianti e studenti avanzati, quindi puoi iniziare da qui o dall'inizio e procedere al tuo ritmo. Questa è la lezione 1 di 4.

Quanto tempo richiede la lezione «GraphQL a confronto con REST»?

La maggior parte delle lezioni CoddyKit richiede circa 5–10 minuti. Ogni lezione è breve e interattiva, quindi fai progressi costanti e riprendi esattamente da dove hai lasciato su web e app.

Posso scrivere ed eseguire codice in questa lezione PHP Academy?

Sì. Ogni lezione PHP Academy include un editor di codice integrato, quindi scrivi ed esegui codice reale direttamente nel tuo browser e ricevi feedback istantaneo dall'IA — nessuna configurazione locale necessaria.

Tutte le lezioni di questo corso

← Torna a PHP Academy