A pergunta por trás de GraphQL vs REST

Alguém numa reunião de planejamento diz "devíamos migrar para GraphQL". Ninguém na sala quer ser quem diz não a uma coisa mais nova, então o time passa um trimestre nisso. Dezoito meses depois, há dois jeitos de ler um Course da mesma tabela, e nenhum deles pode ser apagado.

Essa é a falha de que este curso trata. O GraphQL não é ruim. A falha é um time adotar o GraphQL sem ter o problema que ele resolve.

O padrão honesto

Para a maioria dos times Rails a resposta é não, e um engenheiro sênior deve conseguir dizer isso numa sala sem parecer reacionário.

Aqui vai a versão curta; o resto do curso é a longa. O GraphQL existe para deixar um cliente que você não controla pedir o formato dos dados de que precisa. Se a sua aplicação renderiza HTML no servidor e o entrega pelo Turbo, esse cliente não existe. O navegador não pede campos. Ele pede uma página, e o seu controller já sabe o que vai nela.

Esta aplicação é quase toda esse caso. Ela é Hotwire em primeiro lugar: o servidor renderiza a página e o Turbo troca pedaços dela. O JSON que ela serve é uma API pequena e versionada para parceiros (learners, certificates e activity, em partners/api/v1), alguns endpoints por trás dos exercícios de código e um endpoint de preferências do usuário. Ela também envia webhooks em JSON para os parceiros. Cada um tem um consumidor conhecido e um formato fixo. Adotar GraphQL aqui significaria construir um segundo caminho paralelo para tirar dados dos mesmos models, para clientes que nunca pediram isso.

A condição que muda a resposta

A resposta deixa de ser não numa condição específica, e essa condição não é "temos uma API". É esta: vários clientes heterogêneos que você não controla, ou que não consegue implantar junto com o servidor.

Um app mobile numa loja de aplicativos é o exemplo mais claro. Você lança a versão 4.2 hoje, e parte dos usuários ainda está na 3.9 em março do ano que vem, porque atualizar é decisão deles, e não sua. Desenvolvedores de terceiros na sua API pública têm o mesmo formato. Assim como quatro times de front end lançando quatro interfaces em cronogramas próprios.

Quando isso é verdade, "acrescentar um campo ao endpoint" deixa de ser uma mudança de uma linha. Deixar cada cliente declarar do que precisa começa a pagar o custo.

O que este curso cobre

A lição 2 defende o GraphQL direito. Ela cobre quanto custam de verdade o excesso e a falta de dados numa resposta, por que uma única ida e volta para um grafo inteiro importa numa conexão móvel ruim e a condição exata de cliente que faz valer a pena.

A lição 3 é a conta. O N+1 vira o padrão em vez da exceção, e o cache HTTP quase some. Nada limita o custo de uma query, a autorização desce para o campo e os erros chegam com um 200.

A lição 4 é o que o REST dá em silêncio, e que os times só notam depois de sair dele. Isso significa chaves de cache, URLs nos logs e no APM, autorização simples e uma história de versionamento que já existe.

A lição 5 é o meio-termo, que costuma ser a resposta certa: sparse fieldsets, alguns endpoints compostos para as telas que precisam deles ou um backend-for-frontend.

A lição 6 cobre as especificidades do Rails. Ela mostra como o graphql-ruby se encaixa, por que um único endpoint POST pula quase toda a maquinaria HTTP do Rails e como são o batching e os limites de complexidade. Mostra também como os trusted documents recuperam parte do que se perdeu. Ela traz o desafio de código.

A lição 7 é o critério de decisão, terminando onde esta lição começou.

Antes de tudo isso

Vá descobrir quais são os seus clientes: não o que o roadmap diz que eles podem ser em dois anos, mas o que são hoje. Quantos são, quem controla o cronograma de deploy deles e quantas telas estão travadas numa ida e volta que você não consegue evitar?

Esse inventário decide a questão, e quase nada mais decide.