Programação · web · API

REST vs GraphQL

Estás a construir uma API e a primeira grande bifurcação é o estilo: REST ou GraphQL. Resolvem o mesmo problema — deixar os clientes ler e escrever dados via HTTP — mas colocam o controlo em mãos diferentes. Este guia compara-os honestamente quanto à obtenção de dados, cache, complexidade e tooling, para escolheres com conhecimento de causa.

A diferença fundamental

• REST — muitos endpoints (URLs), cada um devolvendo uma forma fixa de dados. Chamas /users/42 e obténs o que esse endpoint foi feito para devolver. É o servidor que decide a forma.
• GraphQL — um único endpoint ao qual o cliente envia uma query que nomeia exatamente os campos que quer, e recebe apenas esses. É o cliente que decide a forma.

Ambos passam por HTTP e falam, em geral, JSON. A diferença: quem controla o que volta.

O mesmo pedido, das duas formas

Obter o nome de um utilizador e os títulos dos seus posts. Em REST são muitas vezes duas chamadas; em GraphQL uma query precisa:

-- REST (muitas vezes duas idas e voltas)
GET /users/42
GET /users/42/posts

-- GraphQL (uma query, campos exatos)
POST /graphql
{ user(id: 42) { name posts { title } } }

Over-fetching e under-fetching

É o argumento principal do GraphQL. Com as respostas fixas do REST, encontras muitas vezes:

• O over-fetching — o endpoint devolve muito mais do que o necessário (dezenas de campos para mostrar um nome).
• O under-fetching — um endpoint não chega, fazes várias outras chamadas para construir um ecrã.

O GraphQL evita os dois: o cliente pede exatamente os campos que quer, numa única query. Para apps com muitos ecrãs (sobretudo móveis), essa precisão é a principal razão de adoção.

Onde o REST ainda ganha

• Cache — URLs distintos + GET fazem o REST funcionar naturalmente com as caches HTTP e as CDN. O GraphQL (POST para um endpoint) precisa de uma cache cliente ou de queries persistidas.
• Simplicidade — para dados orientados a recursos, o REST tem menos a aprender e a operar; sem esquema, resolvers nem limites de custo de query.
• Tooling e ubiquidade — o REST está em todo o lado, com um tooling maduro e gratuito e uma curva de aprendizagem suave.

Onde o GraphQL ganha

• Dados flexíveis e precisos — os clientes obtêm exatamente aquilo de que precisam, nada mais.
• Menos idas e voltas — dados ligados numa única query em vez de várias chamadas.
• Um esquema tipado — um contrato autodocumentado e um tooling poderoso (introspeção, codegen).

O custo: mais complexidade no servidor (esquema, resolvers, proteção contra queries dispendiosas) e uma cache para desenhar em vez de obtida de graça.

Como escolher

• Escolhe REST para APIs mais simples, orientadas a recursos, em que a cache HTTP gratuita, a ubiquidade e uma curva suave contam.
• Escolhe GraphQL quando os clientes têm necessidades de dados variadas e em evolução e queres evitar o over/under-fetching — e consegues absorver a complexidade extra no servidor.
• Ambos é válido — muitos sistemas expõem REST para o acesso simples/público e GraphQL para as apps cliente ricas.

Perguntas frequentes

Qual é a diferença entre REST e GraphQL?

REST e GraphQL são dois estilos para construir uma API web. Uma API REST expõe muitos URLs (endpoints), cada um devolvendo uma forma de dados fixa — chamas /users/42 e obténs o que esse endpoint devolve. GraphQL expõe um único endpoint ao qual o cliente envia uma query que descreve exatamente os campos que quer, e recebe apenas esses. Em suma: com REST o servidor decide a forma da resposta por endpoint; com GraphQL decide-a o cliente por query. Ambos passam por HTTP e trocam, em geral, JSON.

O GraphQL é melhor do que o REST?

Nenhum é universalmente melhor — fazem compromissos diferentes. O GraphQL brilha quando os clientes precisam de dados flexíveis e precisos (ex.: ecrãs móveis variados) porque evita o over-fetching e o under-fetching e agrupa várias chamadas numa única query. O REST brilha em APIs simples orientadas a recursos e beneficia de uma cache HTTP gratuita e madura e de um tooling sólido. O GraphQL acrescenta complexidade no servidor (esquema, resolvers, controlo do custo das queries); o REST pode exigir várias idas e voltas. Escolhe consoante as necessidades de dados dos teus clientes, não a moda.

O que é o over-fetching e o under-fetching?

O over-fetching é quando um endpoint devolve mais dados do que o necessário — pedes um utilizador e recebes dezenas de campos para mostrar apenas um nome, desperdiçando largura de banda. O under-fetching é quando um endpoint não devolve o suficiente, obrigando-te a várias chamadas para montar o que um ecrã pede. O REST está sujeito a isso porque cada endpoint tem uma resposta fixa. O GraphQL evita ambos ao deixar o cliente pedir exatamente os campos que quer numa única query — é o seu principal atrativo.

REST ou GraphQL: qual fica melhor em cache?

O REST é geralmente mais simples de pôr em cache. Como o REST usa URLs distintos e métodos HTTP (sobretudo GET para leituras), funciona naturalmente com a cache HTTP, as CDN e a cache do navegador indexadas no URL. O GraphQL envia, em geral, as queries em POST para um único endpoint, pelo que a cache HTTP padrão não se aplica logo, e apoias-te numa cache do lado do cliente (como o Apollo) ou em queries persistidas. Se uma cache HTTP padrão e gratuita conta muito para ti, é um ponto a favor do REST.

Em resumo

REST e GraphQL não são inimigos — são duas respostas a «quem decide a forma da resposta?». O REST mantém-na do lado do servidor com endpoints simples e cacheáveis; o GraphQL confia-a ao cliente para queries precisas e flexíveis, ao preço de uma complexidade acrescida. Escolhe consoante as necessidades de dados dos teus clientes e o teu apetite por complexidade operacional — e lembra-te de que podes usar ambos onde cada um for adequado.