GraphQL vs. REST: um guia completo

APIs são a espinha dorsal dos aplicativos web e mobile modernos. Praticamente todo app no seu celular e todo site que você visita usam APIs para buscar e interagir com os dados exibidos na tela. 

REST e GraphQL são dois dos paradigmas de design de API mais comuns. Neste guia, vamos explorar as diferenças fundamentais, os benefícios e os melhores casos de uso de cada um para você escolher a abordagem que mais faz sentido para o seu projeto.

Calma lá, o que é uma API?
Se você é totalmente novo no conceito de API (Application Programming Interface), vale a pena fazer nosso curso Streamlined Data Ingestion with Pandas. Ele mostra como aplicações usam APIs para se comunicar com outros programas — e vice-versa — sem que nenhum dos lados precise conhecer os detalhes do funcionamento interno do outro. O curso vai deixar você por dentro das regras e protocolos que as aplicações usam para solicitar e trocar informações.

O que é REST?

REST (Representational State Transfer) é um estilo arquitetural usado para desenvolver serviços web desde o começo dos anos 2000. Ele define um conjunto de restrições e princípios para construir APIs escaláveis e stateless. APIs REST (também chamadas de RESTful) são leves e podem ser usadas em qualquer linguagem ou plataforma que suporte HTTP.

Se você está começando com APIs REST, recomendo se acostumar a interagir com elas antes de desenvolver a sua. Isso ajuda a entender como funcionam e quais são as boas práticas. Dê uma olhada em Intermediate Importing Data in Python ou Intermediate Importing Data in R para começar. Ambos os cursos têm capítulos sobre requisições HTTP, raspagem de dados na web e outras coisas legais. 

Conceitos-chave de APIs REST

Vamos entender os conceitos do REST. 

Statelessness

Cada interação entre cliente e servidor é independente. O servidor não armazena dados de sessão do cliente entre as requisições, o que significa que toda requisição do cliente ao servidor deve conter todas as informações necessárias para que o servidor a entenda e processe.

Baseada em recursos

Todo dado ou funcionalidade é tratado como um recurso que pode ser identificado e manipulado por meio de um identificador único, normalmente um URI (Uniform Resource Identifier). 

Por exemplo, em um e-commerce, os recursos podem incluir clientes, produtos, pedidos etc. Cada recurso é identificado por um URI único que funciona como um endereço onde o recurso pode ser acessado. Por exemplo:

• /products pode se referir ao conjunto de todos os produtos.

• /products/123 pode se referir a um produto específico com o ID 123.

Métodos HTTP

APIs RESTful normalmente usam métodos HTTP padrão para operar sobre recursos:

• GET: obter dados do servidor (por exemplo, buscar a lista de produtos).

• POST: enviar dados para o servidor (por exemplo, criar um novo produto).

• PUT: atualizar um recurso existente (por exemplo, alterar detalhes do produto).

• DELETE: remover um recurso (por exemplo, excluir um produto).

Uma requisição padrão de GET ficaria assim:

Exemplo de requisição e resposta REST. Imagem do autor.

APIs REST também usam códigos de status HTTP para comunicar erros, sucesso e outros retornos. E sim, o status 418 I’m a teapot existe mesmo!

Formatos de dados

Uma API RESTful pode usar diferentes formatos para representar e trocar dados, incluindo JSON, XML, HTML, texto puro, YAML e CSV.

O que é GraphQL?

GraphQL é uma linguagem de consulta e um runtime open source para APIs que permite aos clientes solicitar exatamente os dados de que precisam — nada a mais, nada a menos. Ele foi desenvolvido inicialmente pela Meta (antes, Facebook) em 2012 para otimizar a busca de dados em seus apps mobile e liberado ao público em 2015.

Conceitos-chave de APIs GraphQL

Vamos ver as principais ideias por trás do GraphQL.

Consultas específicas do cliente

No GraphQL, o cliente define a estrutura da resposta especificando, na consulta, os campos de que precisa. Isso significa que o cliente pode pedir apenas os dados necessários, evitando over-fetching (trazer dado demais) e under-fetching (trazer dado de menos).

No GraphQL, uma consulta para obter detalhes de um usuário ficaria assim:

Exemplo de requisição e resposta GraphQL. Imagem do autor.

Queries vs. mutations

Enquanto as queries são usadas para ler dados, as mutations servem para criar ou modificar dados. As mutations no GraphQL são análogas às operações POST, PUT e DELETE no REST.

Um único endpoint

Diferente das APIs REST, que podem ter vários endpoints para recursos diferentes, uma API GraphQL normalmente expõe um único endpoint. Esse endpoint lida com todas as queries e mutations, simplificando a interação do cliente com a API.

Schema fortemente tipado

APIs GraphQL são definidas por um schema, que descreve de forma fortemente tipada os modelos de dados disponíveis e seus relacionamentos. Esse schema funciona como um contrato entre cliente e servidor, garantindo que os dados retornados correspondam ao que foi solicitado e estejam no tipo esperado.

Introspecção

O schema do GraphQL é autodescritivo. Os clientes podem usar o recurso de introspecção para consultar o próprio schema e descobrir os tipos, queries, mutations e subscriptions disponíveis, facilitando a exploração e o entendimento da API.

Dados em tempo real

GraphQL oferece atualizações em tempo real por meio de subscriptions. Com elas, os clientes recebem atualizações sempre que os dados de interesse mudam — ideal para apps de chat, feeds ao vivo e outros casos em tempo real.

Principais diferenças entre GraphQL e REST

A tabela abaixo resume as principais diferenças entre APIs GraphQL e REST.

Como quase tudo na vida, cada solução tem seus prós e contras.

Como escolher entre GraphQL e REST

A escolha entre REST e GraphQL depende totalmente das necessidades do seu projeto. Você provavelmente já tem uma noção com base na seção anterior, mas, como regra geral, use REST quando tiver:

• Modelos de dados simples.
• Aplicações que exigem cache extensivo.
• Times já familiarizados com convenções REST.
• Necessidade de respostas padronizadas e previsíveis.

E use GraphQL quando você lida com:

• Modelos de dados complexos, com relacionamentos aninhados.
• Aplicações que precisam de consultas flexíveis e dinâmicas.
• Iteração rápida e menos ajustes no backend.
• Atualizações em tempo real.

REST e GraphQL também podem ser usados juntos em soluções híbridas. Assim, seu projeto aproveita endpoints REST simples e bem definidos e, ao mesmo tempo, a flexibilidade do GraphQL para buscas de dados mais complexas. Por exemplo, em um app de e-commerce, você pode usar REST para autenticação e cadastro de usuários — aproveitando práticas de segurança padrão como OAuth — e usar GraphQL para buscar informações mais aninhadas e complexas, como detalhes de produtos, categorias e avaliações de usuários.

Conclusão

É isso: tanto GraphQL quanto REST têm pontos fortes e limitações e se encaixam em cenários diferentes. A escolha entre eles deve ser guiada pelos requisitos do seu projeto e pela complexidade dos seus dados. 

Dito isso, as duas ferramentas são ótimas de usar e ensinam muito sobre dados. Se tiver oportunidade, vale testar ambas!

E, se depois desta leitura você já sabe qual ferramenta quer usar, é hora do próximo passo! Confira nosso post Mastering API Design: Essential Strategies for Developing High-Performance APIs para aprender a desenhar suas próprias APIs.