GraphQL vs REST em PHP: o que escolher para API em 2024?

Introdução: REST ou GraphQL — a batalha eterna por velocidade e flexibilidade

Olá, desenvolvedor! Se você já escreveu uma API em PHP, certamente já enfrentou o dilema: usar o clássico REST ou o moderno GraphQL. Ambas as abordagens resolvem o mesmo problema — transferência de dados entre cliente e servidor — mas fazem isso de maneiras radicalmente diferentes.

O REST foi o padrão de facto por muitos anos: simples, intuitivo, previsível. Mas com o aumento da complexidade dos frontends (React, Vue, aplicativos móveis), os desenvolvedores reclamam cada vez mais de overfetching (muitos dados na resposta) e underfetching (necessidade de fazer várias requisições para reunir as informações necessárias). É aqui que entra o GraphQL — uma linguagem de consulta que dá ao cliente controle sobre quais dados receber.

Neste artigo, não vamos apenas listar teoria. Vamos pegar projetos PHP reais (Laravel e Symfony), escrever código e ver o que é mais rápido e o que é mais conveniente. Vamos lá!

1. REST API em PHP: o clássico que não morre

Como funciona

REST (Representational State Transfer) é um estilo arquitetural onde cada recurso (usuário, artigo, comentário) tem seu próprio URL. O cliente envia requisições HTTP (GET, POST, PUT, DELETE) e o servidor retorna uma estrutura de dados fixa, geralmente em JSON.

Exemplo de um endpoint REST típico em PHP (sem framework):

// index.php - API REST simples\nheader('Content-Type: application/json');\n\n$method = $_SERVER['REQUEST_METHOD'];\n$uri = $_SERVER['REQUEST_URI'];\n\nif ($method === 'GET' && $uri === '/api/users') {\n    $users = [\n        ['id' => 1, 'name' => 'Alexey', 'email' => 'alex@example.com'],\n        ['id' => 2, 'name' => 'Maria', 'email' => 'maria@example.com']\n    ];\n    echo json_encode($users);\n}\n

Em Laravel fica ainda mais simples:

// routes/api.php\nRoute::get('/users', function () {\n    return User::all(); // Serializado automaticamente em JSON\n});\n

Prós do REST

\n
• Simplicidade de cache: Cache HTTP (ETag, Last-Modified) funciona nativamente.
\n
• Facilidade de depuração: qualquer navegador ou curl mostra a resposta.
\n
• Estabilidade: REST existe desde 2000, documentação e ferramentas (Postman, Swagger) são muito refinadas.
\n

Contras do REST

\n
• Overfetching: se o cliente precisa apenas do nome do usuário, ele ainda recebe email, telefone, endereço.
\n
• Problema N+1: para obter um usuário e seus posts, são necessárias duas requisições (GET /users/1, GET /users/1/posts).
\n

2. GraphQL em PHP: quando o cliente é rei

Como funciona

GraphQL não é um banco de dados, mas uma camada entre o cliente e o servidor. O cliente envia uma requisição POST para um único endpoint (geralmente /graphql) com um corpo de consulta descrevendo quais campos e relações são necessários. O servidor retorna exatamente o que foi solicitado — nem um byte a mais.

Exemplo de implementação em PHP com a biblioteca webonyx/graphql-php:

// schema.php\nuse GraphQL\\Type\\Definition\\ObjectType;\nuse GraphQL\\Type\\Definition\\Type;\n\n$userType = new ObjectType([\n    'name' => 'User',\n    'fields' => [\n        'id' => Type::int(),\n        'name' => Type::string(),\n        'email' => Type::string(),\n    ]\n]);\n\n$queryType = new ObjectType([\n    'name' => 'Query',\n    'fields' => [\n        'user' => [\n            'type' => $userType,\n            'args' => ['id' => Type::int()],\n            'resolve' => function ($root, $args) {\n                return findUserById($args['id']); // Sua lógica\n            }\n        ]\n    ]\n]);\n

E agora a consulta do cliente:

// Cons