5 erros comuns em APIs REST e GraphQL (e como evitar)

Nem todo projeto envolvendo APIs REST e GraphQL dá errado por falta de conhecimento técnico — na maioria das vezes, é por repetir os mesmos erros básicos.

REST organiza dados em torno de recursos e endpoints previsíveis; GraphQL permite ao cliente pedir exatamente os campos que precisa em uma única requisição — a escolha depende mais do formato de consumo dos dados do que de qual é "melhor" em abstrato.

Os tropeços mais comuns

1. Ignorar que graphQL reduz o número de requisições quando o cliente precisa combinar dados de múltiplas fontes numa tela.
2. Ignorar que rEST tende a ser mais simples de cachear em nível de infraestrutura, por depender menos de lógica customizada.
3. Ignorar que documentação clara de contrato de API é essencial em ambas as abordagens, especialmente com múltiplos times consumindo.
4. Ignorar que graphQL pode gerar consultas muito custosas se não houver limitação de profundidade e complexidade no servidor.
5. Ignorar que versionamento é tratado de formas bem diferentes entre REST (URLs versionadas) e GraphQL (evolução do schema).

A boa notícia é que nenhum desses erros é difícil de corrigir uma vez identificado — o problema é raramente pararem para revisar até que algo dê errado.

O padrão por trás da maioria desses erros em APIs REST e GraphQL não é falta de conhecimento técnico — é pressa, falta de revisão e ausência de um processo que force uma segunda checagem antes de algo ir para produção.

O GraphQL, criado pelo Facebook e hoje mantido pela GraphQL Foundation, resolve um problema específico do REST: evitar que o cliente receba dados demais ou de menos em cada requisição. Em vez de múltiplos endpoints fixos, o cliente descreve exatamente quais campos precisa em uma única consulta. Isso é vantajoso em aplicativos móveis com conexão limitada, mas adiciona complexidade de implementação que nem sempre se justifica em um sistema pequeno.

Para uma PME avaliando qual usar, a pergunta prática é: o sistema vai integrar com poucos parceiros de forma previsível (REST costuma bastar) ou vai alimentar múltiplas telas com necessidades de dados muito diferentes, como um app e um painel web (GraphQL tende a economizar chamadas)? A documentação oficial do GraphQL e o verbete da Wikipédia sobre REST são bons pontos de partida para entender as diferenças antes de decidir com o time técnico.

Perguntas frequentes

Como evitar os erros mais comuns em APIs REST e GraphQL?

GraphQL reduz o número de requisições quando o cliente precisa combinar dados de múltiplas fontes numa tela.

Como evitar os erros mais comuns em APIs REST e GraphQL?

Versionamento é tratado de formas bem diferentes entre REST (URLs versionadas) e GraphQL (evolução do schema).

Esta matéria faz parte da cobertura de apis rest e graphql assinada por Beatriz Nogueira na Revista SmartWeb — acompanhe as próximas colunas sobre o tema para aprofundar cada um dos pontos levantados aqui.

Fontes e leitura complementar

• MDN Web Docs
• OWASP Foundation