PHP Academy · Aula

GraphQL versus REST

Entenda quando GraphQL é melhor que REST e por quê.

GraphQL versus REST é uma aula grátis de PHP Academy no CoddyKit. Esta é a aula 1 de 4. Você pode ler a aula completa abaixo gratuitamente — depois pratica ao vivo no navegador com um editor de código integrado e um tutor de IA 24/7. Faz parte do caminho de aprendizado de PHP Academy, e seu progresso é sincronizado entre a web e o app CoddyKit. O curso de PHP Academy inclui 4 aulas no total.

Por que GraphQL?

Você já sabe como publicar APIs REST em PHP. GraphQL não substitui HTTP nem é uma solução mágica — é uma linguagem de consulta e um sistema de tipos que permite ao cliente descrever exatamente o que precisa e receber exatamente isso, em uma única viagem de ida e volta.

Nesta lição, faremos uma comparação honesta entre os dois: onde GraphQL realmente se destaca, quando REST ainda é a escolha certa e quais custos GraphQL traz em termos operacionais.

Obtenção excessiva e insuficiente

Os pontos problemáticos clássicos do REST:

Obtenção excessiva: GET /users/1 retorna 40 campos quando a interface precisa de 3.
Obtenção insuficiente: para renderizar as publicações de um usuário e a contagem de comentários de cada publicação, você chama /users/1, depois /users/1/posts e, em seguida, N pontos de acesso de comentários.

GraphQL reduz tudo isso a uma única requisição declarativa.

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

Um ponto de acesso, esquema tipado

O REST expõe muitas URLs; GraphQL expõe um único ponto de acesso (geralmente POST /graphql) respaldado por um esquema fortemente tipado. O esquema é o contrato — pode ser inspecionado, portanto as ferramentas (preenchimento automático, documentação e geração de código) vêm prontas.

A seguir, há um esquema mínimo em SDL. A estrutura de todas as respostas possíveis é conhecida antecipadamente.

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

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

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

A resposta reproduz a consulta

Uma propriedade importante: a estrutura da resposta JSON é previsível a partir da consulta. Os clientes nunca precisam adivinhar nomes de campos. Isso elimina toda uma categoria de alterações de versão — você adiciona campos sem quebrar clientes antigos e marca campos como obsoletos com @deprecated, em vez de criar URLs /v2.

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

Onde GraphQL supera REST

GraphQL é a escolha mais forte quando:

Você atende a muitos clientes heterogêneos (web, iOS, Android) com necessidades de dados diferentes.
Os dados formam um grafo com relações profundas que os clientes percorrem dinamicamente.
Você quer agregar vários serviços de retaguarda por trás de uma única porta de entrada tipada.
A iteração rápida da interface é importante e você quer evitar alterações intermináveis nos pontos de acesso da retaguarda.

Onde REST ainda prevalece

Não recorra ao GraphQL por reflexo. REST é mais simples e geralmente melhor quando:

Você precisa de cache HTTP — os caches de CDN/de borda usam URLs e verbos como chaves; um único POST /graphql é opaco para eles.
A API é orientada a recursos e estável (CRUD sobre algumas entidades).
Você depende de envios ou transferências de arquivos ou de transmissão contínua, em que multipart e intervalos de bytes são recursos nativos do REST.
Seus consumidores são terceiros que esperam a semântica REST convencional.

Uma comparação rápida em PHP

Aqui estão os mesmos dados reunidos da maneira REST em PHP — observe que o cliente ainda precisaria fazer várias chamadas ou montar manualmente um parâmetro de incorporação. O GraphQL transfere essa lógica de seleção para o cliente.

<?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);

Os custos que o GraphQL acrescenta

O GraphQL transfere a complexidade para o servidor. Estas são novas preocupações que agora ficam sob sua responsabilidade:

Consultas N+1 — resolvedores aninhados executam uma consulta ao banco de dados por nó, a menos que você faça o agrupamento (DataLoader).
Limitação de custo e profundidade das consultas — uma consulta maliciosa profundamente aninhada pode causar uma negação de serviço.
O cache é mais difícil; normalmente você armazena em cache na camada de resolvedores/dados, não no HTTP.
O tratamento de erros é diferente — uma resposta 200 OK ainda pode conter uma matriz errors.

Erros: 200 com uma lista de erros

Ao contrário dos códigos de status do REST, o GraphQL normalmente retorna HTTP 200 e relata falhas parciais no corpo. data pode estar parcialmente preenchido enquanto errors lista o que falhou. Seus clientes precisam verificar ambos.

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

Heurística de decisão

Uma regra prática:

APIs públicas, com muito cache e CRUD de recursos → REST.
APIs internas ou de produto que alimentam clientes sofisticados e variados com dados conectados → GraphQL.
Muitos serviços de back-end para unificar por trás de um contrato tipado → gateway GraphQL.

É comum e saudável usar os dois: REST para webhooks e envios de arquivos, GraphQL para o grafo de leitura do aplicativo.

Servindo GraphQL por HTTP em PHP

Operacionalmente, um ponto de acesso GraphQL em PHP é uma única rota que lê o corpo JSON, extrai query e variables, executa-os no esquema e retorna { data, errors }. Em comparação com as várias rotas do REST, o transporte é uniforme — toda a variação fica na cadeia de consulta enviada pelo cliente.

<?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ção rápida

Quando REST mantém uma vantagem clara sobre GraphQL?

Recapitulação

Você comparou GraphQL e REST em termos práticos:

GraphQL resolve a busca excessiva ou insuficiente com um único ponto de acesso tipado e seleção controlada pelo cliente.
Ele se destaca quando há muitos clientes, dados estruturados como um grafo e agregação no servidor.
REST continua forte para APIs públicas que aceitam cache, CRUD simples, envios de arquivos e consumidores convencionais.
GraphQL transfere os custos para o servidor: N+1, limites de custo das consultas, cache e a semântica de respostas 200 com erros.

A seguir: construir de fato um esquema com webonyx/graphql-php.

Perguntas Frequentes

A aula “GraphQL versus REST” é grátis?

Sim — o texto completo de “GraphQL versus REST” é grátis para ler aqui na web. Para praticá-la interativamente (um editor de código integrado e um tutor de IA 24/7) e desbloquear o restante do curso de PHP Academy, atualize para CoddyKit PRO. O curso de PHP Academy inclui 4 aulas no total.

O que vou aprender em “GraphQL versus REST”?

Entenda quando GraphQL é melhor que REST e por quê. Você pratica PHP Academy com código prático que executa diretamente no navegador, e um tutor de IA 24/7 responde suas dúvidas enquanto trabalha na aula.

Preciso ter experiência prévia para começar PHP Academy?

Nenhuma experiência prévia é necessária. PHP Academy no CoddyKit é estruturado para alunos iniciantes até avançados, então você pode começar aqui ou desde o início e aprender no seu ritmo. Esta é a aula 1 de 4.

Quanto tempo leva a aula “GraphQL versus REST”?

A maioria das aulas CoddyKit leva cerca de 5–10 minutos. Cada uma é compacta e interativa, então você faz progresso constante e retoma exatamente de onde parou entre web e app.

Posso escrever e executar código nesta aula de PHP Academy?

Sim. Cada aula de PHP Academy inclui um editor de código integrado, então você escreve e executa código real direto no navegador e recebe feedback de IA instantaneamente — nenhuma configuração local necessária.

Todas as aulas deste curso

← Voltar para PHP Academy