GraphQL ganha primeira especificação oficial para funcionar sobre HTTP

Desde o lançamento em 2015, a especificação do GraphQL é agnóstica em relação ao transporte. Ela descreve serviços que recebem requisições, executam e produzem respostas, mas deixa a cargo de quem implementa como isso trafega. Para a maioria que usa GraphQL sobre HTTP, a falta de um documento comum dificultava a interoperabilidade com outras ferramentas HTTP e a observability.

A GraphQL over HTTP é um documento novo, complementar à especificação principal, que continua agnóstica. A mudança central é o media type application/graphql-response+json. Antes, muitos servidores respondiam com application/json, e o cliente não distinguia uma resposta GraphQL bem formada do servidor de origem de um erro vindo de proxy, cache ou outro intermediário. O contorno era devolver sempre 200, o que esvaziava o monitoramento (as piadas sobre "200 Not OK"). Agora, com esse media type, o cliente pode parsear o corpo como resposta GraphQL válida independentemente do status. A regra geral: se houve dados, 2xx; se só erros, 4xx ou 5xx. Exemplos citados: 405 para mutation via GET, 406 e 415 para media type não suportado, 431 para headers grandes e 500 para erro de servidor. A especificação também introduz o status 294 Partial Success para quando há dados e erros juntos.

Segundo a fonte, a maioria dos frameworks e bibliotecas já suporta a especificação. Os próximos passos previstos são o verbo HTTP QUERY, persisted documents e request batching, este último útil em composite schemas (Federation).

Em 25 de junho de 2026, o CEVIU noticiou "O método HTTP QUERY", sobre a proposta de um método seguro e idempotente para enviar requisições sem alterar o recurso-alvo. A fonte atual diz que o IETF moveu o QUERY para proposed standard e que o GraphQL pretende suportá-lo, mas na próxima revisão da especificação, não nesta primeira versão.

Para quem opera uma API GraphQL, isso sugere rever a regra de responder 200 para tudo. Dashboards, alertas e caches HTTP passam a ter sinal útil no código de status. Quem escreve clientes ou bibliotecas deve checar o tratamento do novo media type e do 294, já que a especificação ainda deve ganhar o QUERY e o batching.