GraphQL vs. REST para o comércio de empresas

O REST é um estilo de interface de programação de aplicações (API) para sites. Disponibiliza vários endpoints fixos, cada um dos quais devolve um conjunto de dados com uma estrutura predefinida. Por outro lado, o GraphQL é uma linguagem de consulta e uma arquitetura de API que expõe um único endpoint e permite ao cliente especificar exatamente os dados que pretende numa consulta.

A escolha entre REST e GraphQL impacta o seu site, nomeadamente, quantos dados circulam entre os seus sistemas, quantos pedidos uma página precisa de fazer e como as suas integrações evoluem ao longo do tempo. A Shopify tornou o GraphQL a sua API definitiva em outubro de 2024. No ano que antecedeu essa decisão, duplicámos os limites de taxa do GraphQL e reduzimos o custo das consultas baseadas em ligações em 75%.

Este guia explica como o GraphQL e o REST diferem e onde cada um se enquadra melhor. Oferece ainda uma estrutura de decisão para equipas de comércio empresarial que escolhem entre os dois.

REST: a abordagem tradicional

Uma API de e-commerce realiza a troca de dados entre sistemas. Um cliente envia um pedido a um endpoint num servidor, e o servidor responde com dados.

REST significa Representational State Transfer, e as APIs criadas sobre este estilo chamam-se APIs RESTful ou APIs REST. Surgiram no início dos anos 2000 e tornaram-se a norma para serviços web porque usam métodos HTTP comuns como GET, POST, PUT e DELETE para comunicar e transferir dados.

O REST tem várias vantagens que explicam a sua popularidade:

• Endpoints previsíveis: cada recurso tem o seu próprio URL, por isso algo como /products/123 significa sempre a mesma coisa.
• Ferramentas abrangentes: todas as linguagens, gateways e ferramentas de acompanhamento compreendem o REST.
• Códigos de estado HTTP familiares: um 404 ou um 429 indicam ao cliente o que aconteceu sem ser preciso analisar o corpo da resposta.
• Cache HTTP nativa: como cada pedido GET tem um URL estável, os navegadores, as redes de distribuição de conteúdos (CDN) e os proxies podem guardar as respostas em cache sem trabalho adicional.

O REST continua a funcionar bem para operações simples e orientadas para recursos: webhooks, carregamento de ficheiros, dados públicos só de leitura e integrações em que as ferramentas de um parceiro o exigem. O relatório "State of the API" (artigo apenas em inglês) da Postman revelou que 93% das equipas ainda usam REST.

No entanto, o REST apresenta fragilidades em determinados contextos de elevado desempenho. Os endpoints REST devolvem um conjunto fixo de dados, o que pode causar dois problemas:

• Excesso de dados (overfetching): o endpoint pode devolver o registo completo do produto quando o cliente só precisa dos níveis de stock.
• Falta de dados (underfetching): o endpoint pode não devolver tudo o que o cliente precisa, obrigando-o a chamar vários endpoints para montar uma única visualização.

Uma mesma página pode sofrer de excesso e de falta de dados ao mesmo tempo.

À medida que a computação móvel e a computação na nuvem se desenvolveram, estas ineficiências tornaram-se mais evidentes. Foi neste contexto que surgiu uma nova solução, impulsionada pela necessidade de melhorar o desempenho dos sites.

GraphQL: uma alternativa mais eficiente

O Facebook começou a desenvolver o GraphQL em 2012 enquanto recriava as suas aplicações móveis nativas e disponibilizou-o em código aberto em 2015 (artigo apenas em inglês). A GraphQL Foundation, acolhida pela Linux Foundation, mantém a especificação desde 2018. É agora utilizada por grandes plataformas web em todo o mundo.

O GraphQL resolve os problemas de excesso e de falta de dados associados às APIs REST ao introduzir uma linguagem de consulta. O cliente pede apenas os dados que quer, e o servidor devolve exatamente o que foi pedido; nem mais, nem menos.

Como funciona um esquema GraphQL

Uma API GraphQL é definida por um esquema. O esquema declara todos os tipos existentes no sistema (como Product, Variant, Order e Customer) e os campos que cada tipo expõe. Também declara as relações entre eles, para que uma consulta possa obter dados de uma encomenda, dos seus itens e de cada produto sem ter de fazer um pedido separado.

O esquema suporta 3 tipos de operação:

• As consultas (queries) leem dados.
• As mutações (mutations) criam, atualizam ou eliminam dados.
• As subscrições (subscriptions) enviam atualizações ao cliente quando os dados mudam.

Como o esquema tem tipagem forte, o servidor GraphQL valida cada pedido antes de o executar e rejeita qualquer pedido que solicite um campo que não existe.

O esquema também permite a introspeção: o cliente pode consultar a API para conhecer a sua estrutura. Esta funcionalidade permite o preenchimento automático em ferramentas como o GraphiQL e possibilita que os IDEs detetem erros antes da execução de uma consulta.

Eis um exemplo de consulta orientada para o comércio. A consulta pede o título de um produto, as suas duas primeiras variantes com preço e stock e a imagem em destaque do produto:

{ product(handle: "trail-runner") { title featuredImage { url } variants(first: 2) { nodes { title price { amount currencyCode } availableForSale } } } }

A resposta reflete a consulta. Os campos que o cliente não pediu (como descrições, etiquetas ou metadados de SEO) nunca saem do servidor. No REST, o cliente recebe a estrutura de resposta predefinida do endpoint do produto e tem de fazer chamadas separadas para quaisquer dados que a resposta não inclua, como os metafields.

O GraphQL ganhou popularidade porque o problema que o Facebook encontrou cedo é um problema que muitas empresas enfrentam agora: a necessidade de criar aplicações complexas e ricas em dados que sejam, ao mesmo tempo, rápidas e estáveis. É um desafio partilhado tanto pelas lojas online mais pequenas como pelas maiores marcas empresariais.

6 vantagens de usar o GraphQL no comércio empresarial

Se compararmos o GraphQL com o REST, as diferenças podem parecer subtis. Contudo, as APIs são fundamentais para o funcionamento de um site de comércio. Tal como os alicerces de uma casa, a sua escolha de API pode garantir estabilidade a longo prazo ou provocar problemas estruturais à medida que cria tudo o resto. Estes problemas ganharam visibilidade e importância em negócios de grande escala, e ficaram evidentes no comércio empresarial.

Eis um resumo das principais diferenças:

Claro que a flexibilidade do GraphQL implica alguns compromissos. Como o cliente controla a consulta, basta um pedido mal escrito para ficar muito mais dispendioso do que qualquer chamada REST. O servidor também tem mais trabalho; precisa de resolvers para cada campo e de proteções contra nested queries que desencadeiam muitas pesquisas na base de dados.

As equipas empresariais que adotam o GraphQL precisam de uma governação clara e rigorosa quanto ao design do esquema e ao comportamento das consultas. Isto é sinónimo de limites de custo das consultas, limites de profundidade e responsabilidade partilhada sobre o esquema. Inscreva estes aspetos nos seus requisitos de software empresarial desde o início.

As secções seguintes descrevem os benefícios que fazem do GraphQL uma escolha sólida nos cenários em que mais se adequa: clientes variados, modelos de dados interligados, múltiplas fontes de dados e experiências de compra sensíveis ao desempenho.

1. Adequado a dados complexos

Os dados do comércio empresarial formam uma rede de entidades interligadas, que pode ser visualizada como um gráfico. Um produto tem variantes, e cada variante tem inventário em vários locais. Uma encomenda faz referência a clientes, descontos e expedições. Uma conta B2B tem as suas próprias listas de preços e condições de pagamento. O REST achata estas estruturas de dados em endpoints por recurso. À medida que o modelo de dados cresce, aumenta também o número de chamadas à API necessárias para montar uma única visualização. A latência cresce ao ritmo do gráfico.

O esquema descreve diretamente as relações entre os dados, pelo que basta uma consulta para obter todos os dados necessários a uma visualização. Como tal, o GraphQL é uma componente essencial do modelo de dados unificado da Shopify.

A Tecovas, retalhista de vestuário western, precisava de um sistema que oferecesse APIs robustas a par de funcionalidades essenciais. "Quero encontrar sistemas que resolvam os problemas do dia a dia por mim, mas que também ofereçam extensibilidade, um conjunto robusto de APIs e a capacidade de personalizar para os nossos processos de negócio específicos", afirma Kevin Harwood, CTO da Tecovas.

A Tecovas usa o Shopify POS como um sistema de inventário integrado. Os colaboradores conseguem verificar níveis de stock atualizados quando um cliente pede um determinado artigo. A sua montra personalizada tem por base o Shopify Hydrogen, que consulta a Storefront API do GraphQL (apenas em inglês) para obter dados de produtos, coleções e carrinho.

2. Menos transferência de dados

Os endpoints REST devolvem um conjunto fixo de dados, que pode ser mais do que o cliente precisa (excesso de dados). Devolver mais dados do que o necessário é ineficiente e pode gerar latência.

No comércio empresarial, até os milissegundos têm impacto. Por cada 32 milissegundos de atraso na resposta de uma loja às interações, a conversão tende a cair cerca de 1,5%.

O GraphQL limita a obtenção de dados aos campos que o cliente pede. Ao reduzir a transferência de dados desnecessária, os sistemas que usam APIs GraphQL conseguem reduzir o uso de largura de banda e melhorar o desempenho.

3. Menos idas e voltas ao servidor

Como os endpoints REST não conseguem apontar para pontos de dados precisos, uma única visualização pode exigir vários pedidos (falta de dados). Cada pedido obriga a uma ida e volta completa ao servidor.

Uma página de produto é um bom exemplo. Na REST Admin API (apenas em inglês) da Shopify, a resposta de um produto chega como uma carga fixa, e dados relacionados, como os metafields, exigem pedidos adicionais. Montar uma visualização completa de produto pode, desta forma, exigir várias chamadas a endpoints, cada uma devolvendo campos que a página não vai usar. A mesma visualização precisa apenas de uma consulta GraphQL que nomeia apenas os campos de que precisa.

Multiplique isto por uma sincronização de catálogo, uma integração de planeamento de recursos empresariais (ERP) ou uma aplicação de ponto de venda (POS) a verificar stock em tempo real. A diferença é mensurável. Menos idas e voltas significam tempos de carregamento mais rápidos e uma experiência de utilização mais fluida.

4. Melhor experiência para programadores

O REST é familiar para muitos programadores devido à sua longa história. O GraphQL pode exigir mais à partida, mas compensa com as ferramentas que oferece. O esquema tem tipagem forte e documenta-se a si mesmo. Um programador pode explorar uma API que não conhece, usar preenchimento automático nas consultas e detetar erros antes de executar seja o que for. Um esquema com tipagem forte também ajuda a manter a integridade dos dados ao longo do tempo.

Há nuances que as equipas empresariais devem prever:

• Tratamento de erros: o GraphQL devolve HTTP 200 mesmo quando parte de uma consulta falha, com os detalhes num array errors. A GraphQL Admin API da Shopify documenta explicitamente esta diferença (apenas em inglês). Os clientes têm de inspecionar o corpo da resposta em vez de confiarem nos códigos de estado.
• Complexidade do servidor: cada campo precisa de um resolver. Os resolvers ingénuos podem desencadear uma consulta à base de dados por cada item de uma lista, originando o problema "N+1" (apenas em inglês). Camadas de agrupamento (batching) e de cache resolvem isto, mas alguém tem de as criar.
• Governação: os clientes escrevem as suas próprias consultas, logo, o responsável pela API precisa de publicar limites de custo ou de profundidade das consultas. As alterações ao esquema também precisam de revisão entre as equipas relevantes. O Admin API da Shopify, por exemplo, aplica limites de taxa com base no custo calculado da consulta (apenas em inglês) e não no número de pedidos.

5. Evolução mais fácil da API

As APIs mudam ao longo do tempo. No REST, uma alteração disruptiva à estrutura de uma resposta implica uma nova versão (/v2/) e um período de migração para cada cliente.

O GraphQL foi criado para fazer evoluir um esquema sem números de versão. Podem ser adicionados campos a qualquer momento. Os clientes existentes não são afetados, porque só recebem os campos que pediram. Os campos antigos são marcados com uma diretiva de descontinuação que continua a devolver dados, mas avisa os programadores nas suas ferramentas. Os campos removidos devolvem um erro no momento da validação, antes de a consulta ser executada.

Isto não torna as alterações disruptivas impossíveis. A Shopify continua a versionar as suas APIs trimestralmente por essa mesma razão. O que o GraphQL elimina é a necessidade de versionar toda a API sempre que um campo muda.

6. Desempenho reforçado

Todas estas vantagens podem parecer abstratas, agora, como é que se traduzem em desempenho real? Ao longo de quase 200 000 pontos de dados publicamente disponíveis, as lojas Shopify renderizam até 2,4 vezes mais depressa, e 1,8 vezes mais depressa em média, face a lojas noutras plataformas.

O GraphQL contribui para a velocidade da Shopify, mas não é o único fator explicativo. A velocidade do site também está relacionada com a plataforma: alojamento global, entrega via CDN, cache do navegador, compressão e otimização de imagens. O GraphQL reduz os dados e as idas e voltas de que uma página precisa. A plataforma determina a rapidez com que chega o resto da página.

A Shopify e o GraphQL

A Shopify começou a usar o GraphQL quando o Facebook o lançou publicamente. Na altura, havia poucas boas práticas e, enquanto adotantes pioneiros, aprendemos o GraphQL do zero. Desde então, o GraphQL tornou-se muito mais popular e ainda mais importante para a infraestrutura da Shopify, e as montras Shopify colheram estes benefícios.

Em outubro de 2024, anunciámos que o GraphQL se tornaria a API da Shopify. Desde 1 de abril de 2025, todas as aplicações novas submetidas à Shopify App Store têm de usar GraphQL. A REST Admin API está marcada como legada (apenas em inglês), embora continue a funcionar. As novas funcionalidades da plataforma são lançadas primeiro em GraphQL, e algumas são exclusivas do GraphQL, como o apoio para 2000 variantes de produto e os metaobjects.

A Storefront API usa GraphQL, e a Admin API está disponível através de GraphQL. Ferramentas como as Functions, as extensões de UI e o App Bridge usam o GraphQL como a sua principal interface de API.

Usar ambos durante uma migração empresarial

Ao fazer uma modernização de plataforma não tem de mover todas as integrações de uma só vez. É possível correr o REST e o GraphQL lado a lado durante algum tempo, e foi assim que a Skullcandy abordou a mudança.

A Skullcandy migrou para a Shopify em 90 dias. Substituiu um check-out personalizado de cinco passos pelo Shopify Checkout e descontinuou um sistema autónomo de gestão de informação de produtos (PIM). O processamento de encomendas assenta em APIs REST e webhooks. As atualizações de inventário em massa são efetuadas através da API GraphQL, que permite atualizar centenas de registos numa única chamada, em vez de os atualizar individualmente. As mesmas interfaces REST e GraphQL também servem de base a novas aplicações.

Após mudar de plataforma para a Shopify, os resultados da Skullcandy foram imediatos. O tempo de carregamento da sua página inicial caiu de 2,8 segundos para 0,8 segundos no dia a seguir ao lançamento. A primeira época festiva completa da Skullcandy na Shopify trouxe um crescimento de receita de 45% em termos homólogos. O seu maior lançamento de produto registou um pico de 200% nas visitas, sem quaisquer problemas de desempenho.

Quando usar GraphQL vs. REST

Tanto o REST como o GraphQL estão hoje em funcionamento na Shopify. Há uma decisão prática a tomar sobre qual usar.

Escolha o GraphQL quando o trabalho envolver:

• Modelos de dados complexos: produtos com muitas variantes, inventário em vários locais, listas de preços B2B ou metaobjects que precisam de ser obtidos em conjunto.
• Clientes variados: web, móvel, POS e agentes de IA que precisam, cada um, de uma fatia diferente dos mesmos dados.
• Montras personalizadas: criações headless no Hydrogen ou noutra framework, em que a velocidade da página depende de minimizar os pedidos.
• Integrações de longa duração: ligações a ERP, sistemas de gestão de encomendas (OMS) e PIM que terão de evoluir durante anos sem falhar.

O REST continua a ser adequado quando:

• A operação é uma simples leitura ou escrita de um único recurso.
• As ferramentas de um parceiro exigem REST, ou a integração já está criada e estável.
• Estão envolvidos webhooks ou carregamentos de ficheiros.

É possível usar ambos durante a migração. Pode manter em funcionamento as integrações REST existentes enquanto o novo trabalho arranca em GraphQL. Migre primeiro as integrações de maior volume ou mais complexas, onde os ganhos são maiores. Integre esta sequência num plano mais amplo de transformação das tecnologias de informação, em vez de a tratar como uma reescrita isolada.

Para o comércio empresarial na Shopify, o GraphQL é a escolha mais sólida em determinadas circunstâncias. É a API onde as novas funcionalidades são lançadas, e é a API em torno da qual as próprias ferramentas da Shopify foram criadas.