GraphQL ou REST: como decidir para uma nova API

O que é

GraphQL (introdução citada) é uma linguagem de consulta combinada com um runtime no servidor que executa as consultas sobre um sistema de tipos definido por você. O cliente envia uma consulta com o formato dos dados que deseja e recebe exatamente esses dados em uma única requisição. A API evolui adicionando campos e marcando os antigos com @deprecated, em vez de recorrer a versionamento. A orientação sobre GraphQL sobre HTTP (citada) descreve o formato operacional: um único endpoint, normalmente /graphql; POST para queries e mutations, com GET opcional para queries; e um status 2xx mesmo quando a resposta contém erros, porque o HTTP não tem um código de status para sucesso parcial. Uma API no estilo REST, por sua vez, expõe recursos em URLs, usa métodos e códigos de status para expressar a semântica e se apoia no mecanismo do próprio HTTP para cache e erros.

Por que importa

A escolha é arquitetural e difícil de reverter. Ela muda o funcionamento do cache, a forma de reportar erros, o cálculo dos limites de taxa (rate limits) e as ferramentas de que os clientes precisam.

Como aplicar

• Escolha GraphQL quando muitos clientes diferentes (web, mobile, aplicações de parceiros) precisam de fatias distintas de um grafo de dados conectado, quando o over-fetching ou a multiplicação de requisições é um problema medido e quando você controla os clientes o suficiente para distribuir uma biblioteca cliente de GraphQL.
• Escolha REST quando a API é orientada a recursos e pública, quando o cache HTTP por URL é importante, quando os integradores são scripts, webhooks e agentes que falam HTTP puro, ou quando as ferramentas de operação são construídas em torno de códigos de status e caminhos.
• Se escolher GraphQL, planeje os controles descritos na orientação de segurança do GraphQL (citada): limites de profundidade, limites de largura e de aliases, e análise de complexidade das consultas com orçamentos por cliente; a especificação em si não define esses controles. Planeje também o batching de resolvers para o problema N+1.
• Se escolher REST, planeje seleção de campos, filtragem e endpoints compostos, para que os clientes não sejam forçados a fazer muitas idas e vindas ao servidor.
• Considere usar os dois: REST para a superfície pública e as integrações, GraphQL como backend-for-frontend para as suas próprias interfaces de usuário.

Armadilhas

Adotar GraphQL para fugir do design de API: o schema exige o mesmo cuidado que o design de recursos. Expor GraphQL a chamadores não confiáveis sem limites de custo. Fazer os parâmetros de include aninhado de uma API REST crescerem até virarem uma linguagem de consulta sem restrições e sem a validação do GraphQL. Esperar cache em CDN com GraphQL sobre POST; consultas via GET podem ser cacheadas, mas esbarram nos limites de tamanho da URL.