API em PHP: REST, GraphQL e gRPC — qual escolher em 2025?

Introdução: API não é mágica, é uma ferramenta

Quando seu site em PHP deixa de ser uma página estática e começa a se comunicar com o mundo externo — bots do Telegram, gateways de pagamento ou seu próprio aplicativo mobile — você inevitavelmente encontra as APIs (Interface de Programação de Aplicações). É simplesmente um contrato: "Se você me enviar uma requisição neste formato, eu retorno os dados para você". Hoje, no cenário PHP, temos três grandes protagonistas: o clássico REST, o flexível GraphQL e o ousado gRPC. Qual escolher? Vamos descobrir com exemplos práticos.

Este artigo é para quem já sabe programar em PHP e quer expandir seus horizontes. Não vamos apenas copiar documentação, mas analisar cada protocolo com os olhos de um desenvolvedor resolvendo problemas reais.

REST API em PHP: o clássico testado e aprovado

REST (Transferência de Estado Representacional) não é um protocolo, mas um estilo arquitetural. Ele usa métodos HTTP (GET, POST, PUT, DELETE) para manipular recursos. Se você já escreveu file_get_contents('https://api.exemplo.com/usuarios'), já trabalhou com REST.

Por que o REST continua sendo o rei?

\n
• Simplicidade: qualquer cliente HTTP consegue usá-lo.
\n
• Cache: é possível armazenar em cache requisições GET no nível HTTP.
\n
• Ampla adoção: desde curl até bibliotecas especializadas.
\n

Exemplo de cliente REST em PHP com Guzzle

A biblioteca Guzzle é o padrão de facto para requisições HTTP em PHP. Instale-a via Composer: composer require guzzlehttp/guzzle.

<?php\nrequire 'vendor/autoload.php';\n\nuse GuzzleHttp\\Client;\n\n$client = new Client([\n    'base_uri' => 'https://jsonplaceholder.typicode.com/',\n    'timeout'  => 5.0,\n]);\n\n// Requisição GET\n$response = $client->get('posts/1');\n$post = json_decode($response->getBody(), true);\necho "Título do post: " . $post['title'] . PHP_EOL;\n\n// Requisição POST\n$response = $client->post('posts', [\n    'json' => [\n        'title' => 'Novo post',\n        'body' => 'Texto do post',\n        'userId' => 1\n    ]\n]);\necho "Post criado com ID: " . json_decode($response->getBody(), true)['id'];\n?>

O que fizemos? Apenas enviamos requisições HTTP. REST não exige bibliotecas especiais — você pode até usar file_get_contents() com contexto, mas o Guzzle oferece tratamento de erros, middlewares e transmissão por streaming de forma conveniente.

Quando o REST não é a melhor escolha?

Se você precisa obter dados relacionados (por exemplo, post + autor + comentários), o REST exigirá várias requisições. É aí que o GraphQL entra em cena.

GraphQL em PHP: solicite apenas o que precisa

GraphQL é uma linguagem de consulta desenvolvida pelo Facebook. O cliente descreve a estrutura da resposta. Uma requisição — uma resposta, sem excesso ou falta de dados.

Como o GraphQL funciona em PHP?

No lado do servidor: a biblioteca webonyx/graphql-php (instalação: composer require webonyx/graphql-php). No lado do cliente, é uma requisição HTTP POST comum com corpo em JSON.

Exemplo de consulta GraphQL a partir do PHP

<?php\nrequire 'vendor/autoload.php';\n\nuse GuzzleHttp\\Client;\n\n$client = new Client(['base_uri' => 'https://countries.trevorblades.com/']);\n\n$query = '\nquery GetCountry {\n    country(code: \"BR\") {\n        name\n        capital\n        currency\n        languages {\n            name\n        }\n    }\n}';\n\n$response = $client->post('', [\n    'json' => ['query' => $query]\n]);\n\n$data = json_decode($response->getBody(), true);\necho "País: " . $data['data']['country']['name'] . PHP_EOL;\necho "Capital: " . $data['data']['country']['capital'] . PHP_EOL;\necho "Moeda: " . $data['data']['country']['currency'] . PHP_EOL;\necho "Idiomas: ";\nforeach ($data['data']['country']['languages'] as $lang) {\n    echo $lang['name'] . " ";\n}\n?>