Guias

O GraphQL é uma linguagem de consulta para APIs e, ao mesmo tempo, um runtime que responde a essas consultas com os seus dados. Criado na Facebook em 2012 e lançado como open source em 2015, dá ao cliente — uma interface web, uma aplicação móvel ou outro serviço — uma forma única e precisa de pedir a um servidor exatamente os dados de que precisa, nem mais nem menos. Em vez de o servidor decidir a forma de cada resposta, é o cliente que descreve o que quer, e o servidor devolve os dados com essa mesma forma.

Essa única ideia é o que distingue o GraphQL do estilo REST que o precedeu. Com REST normalmente chama vários pontos de acesso, cada um devolvendo uma estrutura fixa que o servidor definiu de antemão. Com GraphQL envia um único pedido a um único ponto de acesso e especifica os campos que quer; a resposta reflete o seu pedido. O objetivo não é tornar o REST obsoleto, mas resolver problemas concretos que os pontos de acesso fixos criam à medida que uma aplicação e os seus dados crescem.

Como funciona o GraphQL: o esquema

No centro do GraphQL está o esquema, um contrato fortemente tipado que descreve cada tipo de dados disponível e como esses tipos se relacionam. Como o esquema é explícito e tipado, ambos os lados sabem de antemão o que é possível: as ferramentas podem validar uma consulta antes mesmo de a executar, os editores podem completar automaticamente os campos e a documentação pode ser gerada automaticamente a partir do próprio esquema. Esta natureza autodescritiva é uma das vantagens mais práticas do GraphQL.

Uma consulta GraphQL lê-se quase como o JSON que devolve. Nomeia os campos que quer, aninha lá dentro os campos relacionados, e o servidor percorre o esquema para resolver cada um. O mesmo ponto de acesso aceita também mutations, que alteram os dados, e subscriptions, que permitem ao servidor enviar atualizações ao cliente através de uma ligação persistente. Consultas, mutations e subscriptions são os três tipos de operação que a especificação define.

Over-fetching e under-fetching

Dois problemas dos pontos de acesso REST fixos explicam grande parte do apelo do GraphQL: o over-fetching e o under-fetching. O over-fetching acontece quando um ponto de acesso devolve muito mais dados do que um ecrã necessita, desperdiçando largura de banda. O under-fetching é o oposto: um único ponto de acesso não devolve o suficiente, pelo que o cliente tem de fazer várias idas e voltas para compor uma só vista. Como um cliente GraphQL pede com precisão os campos de que precisa num único pedido, evita ambos de uma só vez.

• Linguagem de consulta para APIs: o cliente pede exatamente os campos de que precisa
• Esquema fortemente tipado = autodocumentado, validado, com preenchimento automático
• Três operações: consultas (leitura), mutations (escrita), subscriptions (push)
• Resolve o over- e o under-fetching do REST num único pedido
• Compromissos: caching HTTP mais difícil, salvaguardas de custo; REST mais simples para APIs pequenas

GraphQL e os frameworks front-end

Esta precisão é especialmente valiosa para frameworks front-end como React, Vue, Svelte e Angular, em que um componente precisa muitas vezes de uma fatia específica de dados. Um componente pode pedir exatamente os campos que renderiza e, à medida que a interface evolui, a consulta evolui com ela, sem esperar que uma equipa de back-end crie um novo ponto de acesso. Bibliotecas cliente maduras acrescentam por cima caching, agrupamento de pedidos e gestão de estado, e é por isso que o GraphQL se tornou popular nos front-ends orientados a componentes.

Os compromissos, com honestidade

O GraphQL não é automaticamente a escolha certa, e ser honesto quanto aos seus compromissos importa. O seu único ponto de acesso dinâmico torna mais difícil o simples caching HTTP de que o REST goza, pelo que o caching costuma mudar-se para o cliente ou para uma camada especializada. Consultas escritas sem cuidado podem pedir dados profundamente aninhados e sobrecarregar o servidor, razão pela qual as APIs em produção acrescentam limites de profundidade, análise de custo e outras salvaguardas. Para uma API pequena com necessidades estáveis e previsíveis, o REST é muitas vezes mais simples e perfeitamente suficiente.

O que o GraphQL não é

Também vale a pena ser claro sobre o que o GraphQL não é. Não é uma base de dados nem um motor de armazenamento: coloca-se à frente das suas fontes de dados existentes — sejam bases de dados, APIs REST ou outros serviços — e os resolvers vão lá buscar os dados. Também não está preso a uma única linguagem ou framework; há servidores e clientes em todo o ecossistema, e a especificação é mantida pela GraphQL Foundation, neutra face aos fornecedores, e não por uma única empresa.

GraphQL vs REST: como escolher

Escolher entre GraphQL e REST depende da forma da sua aplicação, não da moda. O GraphQL brilha quando muitos clientes diferentes precisam de fatias diferentes de um grafo de dados complexo e interligado, quando as equipas de front-end e back-end querem avançar de forma independente, ou quando reduzir as idas e voltas em ligações lentas é prioritário. O REST continua a ser uma excelente escolha por omissão para serviços mais simples, APIs públicas que beneficiam do caching HTTP e equipas que valorizam a sua ubiquidade e simplicidade.

Dito de forma simples, o GraphQL é uma maneira de deixar o cliente pedir exatamente os dados que quer, descritos por um esquema tipado, servidos a partir de um único ponto de acesso. Não substitui as bases de dados, o REST nem os seus serviços existentes; organiza a forma como os clientes falam com eles. Saber que problemas resolve — e os custos de caching e complexidade que introduz — é o que lhe permite recorrer a ele quando encaixa realmente e deixá-lo de lado quando o REST é a melhor ferramenta.