REST vs GraphQL: Qual paradigma de API?
O REST expõe endpoints de recursos fixos com semântica HTTP; o GraphQL expõe um único endpoint onde os clientes solicitam exatamente os campos de que precisam.
O REST mapeia recursos para URLs e se apoia em caching HTTP, status codes e simplicidade, mas pode fazer over-fetch ou under-fetch para clientes complexos. O GraphQL permite que clientes especifiquem consultas precisas contra um schema tipado, reduzindo round trips e over-fetching, ao custo de mais complexidade no servidor e caching mais delicado. O REST favorece simplicidade e caching nativo de HTTP; o GraphQL favorece busca de dados flexível e conduzida pelo cliente.
| REST | GraphQL | |
|---|---|---|
| Endpoints | Muitos recursos | Um endpoint |
| Busca de dados | Formatos fixos | Especificada pelo cliente |
| Caching | Nativo de HTTP | Custom / persisted |
| Schema | OpenAPI (opcional) | Embutido, tipado |
| Melhor para | APIs simples/cacheáveis | Clientes complexos e variados |
Caso de uso e tradeoffs
O REST atende APIs no estilo CRUD, endpoints públicos e qualquer coisa que se beneficie de caching HTTP e simplicidade. O GraphQL atende clientes ricos (mobile, dashboards) que precisam de dados flexíveis e agregados sem muitos round trips, aceitando complexidade em resolvers, caching e controle de custo de consultas.
Em CI
Pipelines de REST validam o OpenAPI e executam testes de contrato. Pipelines de GraphQL verificam o schema, executam codegen para clientes tipados e protegem contra mudanças de schema que quebram compatibilidade. Ambos rodam em runners gerenciados, onde runners mais rápidos encurtam as etapas de codegen e de verificação de schema.
O veredito
APIs simples, cacheáveis e orientadas a recursos: REST. Clientes complexos que precisam de busca de dados flexível e precisa a partir de muitas fontes: GraphQL. Muitas equipes mantêm o REST para APIs públicas/simples e adotam o GraphQL onde as necessidades de dados do cliente são variadas e intensivas em agregação.