WordPress REST API vs. GraphQL em 2026: O confronto arquitetural

Esta escolha assenta hoje em requisitos de engenharia mensuráveis: quantos pedidos uma página precisa, quanto JSON o navegador tem de processar, como as respostas são guardadas em cache no Edge, como o frontend obtém os seus tipos e quem mantém o código adicional. Ambas as opções são maduras. Este guia compara-as nesses pontos, com cada nome de API, definição e valor por omissão verificado no REST API Handbook e na documentação do WPGraphQL.

#1. Diferenças entre REST API e GraphQL no WordPress

REST (endpoint-driven)
  GET /wp-json/wp/v2/posts/101
  GET /wp-json/wp/v2/users/4
  GET /wp-json/wp/v2/categories?post=101
  = several HTTP requests, each with a fixed response shape

GraphQL (document-driven)
  POST /graphql
  query SinglePost {
    post(id: "101", idType: DATABASE_ID) {
      title
      date
      author { node { name } }
      categories { nodes { name slug } }
    }
  }
  = one HTTP request, the client names every field it wants

O modelo da REST API baseia-se em recursos fixos. Um pedido a /wp-json/wp/v2/posts devolve a representação completa do post: conteúdo renderizado, excerto, GUID, estado dos comentários, links e mais. O WPGraphQL inverte esta lógica. O cliente envia um documento de query e o servidor devolve apenas os campos que esse documento indica.

#Over-fetching e under-fetching na REST API

A equipa do WPGraphQL descreve o problema da REST como over-fetching e under-fetching em simultâneo: o endpoint de posts devolve IDs de categorias, IDs de tags, conteúdo e excerto de que uma listagem não precisa, mas continua a não incluir o nome e o avatar do autor, o que obriga a mais pedidos (WPGraphQL vs WP REST API).

O core tem duas respostas para isto, muitas vezes ignoradas. O parâmetro global _fields devolve apenas um subconjunto de campos, por exemplo ?_fields=id,title,link, e desde o WordPress 5.3 suporta propriedades aninhadas, como uma única chave de meta. O parâmetro _embed inclui os recursos ligados (autor, imagem de destaque, termos) na mesma resposta, e desde o WordPress 5.4 pode limitá-lo a relações de link específicas (Global parameters). Com ambos, uma listagem REST pode aproximar-se de um payload GraphQL. O que continua a faltar à REST é um schema tipado contra o qual o cliente possa fazer queries.

#2. Vantagens e desvantagens da WordPress REST API

A WordPress REST API faz parte do core há uma década e está mais robusta do que nunca.

• O ponto forte: funciona de imediato. Não são necessários plugins adicionais para a funcionalidade básica. É facilmente guardada em cache ao nível HTTP com CDNs comuns, porque cada recurso tem o seu próprio URL.
• O ponto fraco: over-fetching por omissão. Se só precisa do título e do slug de um post e se esquece do _fields, a REST envia o objeto completo do post, incluindo conteúdo e metadados. Isto desperdiça largura de banda, sobretudo em dispositivos móveis.

A REST API usa JSON nos pedidos e nas respostas, e qualquer linguagem capaz de fazer pedidos HTTP e ler JSON consegue utilizá-la (REST API Handbook). É por isso que quase todas as plataformas de integração, conectores de CRM e consumidores de webhooks falam primeiro REST.

#3. Vantagens e desvantagens do WPGraphQL

O GraphQL (normalmente implementado através do WPGraphQL) permite ao programador de frontend definir a forma da resposta.

• O ponto forte: um pedido, exatamente os dados que pretende. Pode obter um post, as suas categorias, os 3 artigos mais recentes do autor e as definições do site numa única ida e volta de rede. O schema é fortemente tipado e cada campo declara o seu tipo.
• O ponto fraco: exige um plugin adicional para manter. A complexidade das queries pode, por vezes, originar consultas lentas à base de dados se não for otimizada com cache de objetos (Redis).

Os dados do plugin, lidos no diretório de plugins do wordpress.org a 14 de outubro de 2026: WPGraphQL 2.24.0, requer WordPress 6.0 e PHP 7.4, testado até ao WordPress 7.0.7, mais de 30.000 instalações ativas. A página do plugin indica que o WPGraphQL está a tornar-se um Canonical Plugin no WordPress.org. Segue o Semantic Versioning, pelo que uma subida de versão major sinaliza alterações incompatíveis e vale a pena ler as notas de lançamento antes de atualizar.

#4. Como o WPGraphQL resolve o problema N+1

Um resolver ingénuo para “os últimos 20 posts e o nome do autor de cada um” executa uma consulta para os posts e depois uma consulta por autor. É o problema N+1. O WPGraphQL evita-o com o padrão DataLoader: durante a resolução, recolhe os IDs de que precisa (todos os valores de post_author, por exemplo) e carrega-os num único lote. No exemplo da própria documentação do WPGraphQL, as consultas SQL para os autores de cinco posts descem de cinco para uma (WPGraphQL vs WP REST API).

SELECT * FROM wp_users WHERE ID IN (2, 5, 8, 14);

Além disso, o WPGraphQL tem uma Model Layer: um conjunto de classes PHP que envolvem os objetos do WordPress e verificam campos sensíveis, como o endereço de email de um utilizador, antes de serem devolvidos (WPGraphQL concepts).

#Como estender o esquema do WPGraphQL em PHP

<?php
declare(strict_types=1);

add_action('graphql_register_types', function (): void {
    register_graphql_object_type('PerformanceMetrics', [
        'description' => __('Core Web Vitals medidos de um artigo', 'wppoland'),
        'fields' => [
            'lcpSeconds' => ['type' => 'Float'],
            'inpMilliseconds' => ['type' => 'Int'],
            'clsScore' => ['type' => 'Float'],
        ],
    ]);

    register_graphql_field('Post', 'cwvMetrics', [
        'type' => 'PerformanceMetrics',
        'resolve' => function ($post): ?array {
            $raw = get_post_meta($post->databaseId, '_wppoland_cwv_data', true);
            if (!is_array($raw)) {
                return null;
            }
            return [
                'lcpSeconds' => isset($raw['lcp']) ? (float) $raw['lcp'] : null,
                'inpMilliseconds' => isset($raw['inp']) ? (int) $raw['inp'] : null,
                'clsScore' => isset($raw['cls']) ? (float) $raw['cls'] : null,
            ];
        },
    ]);
});

#5. Como criar um endpoint REST personalizado no WordPress

O padrão do core é register_rest_route() no hook rest_api_init, ou uma classe que estende WP_REST_Controller. As regras do handbook que contam em produção (Adding custom endpoints):

• Desde o WordPress 5.5, uma rota registada sem permission_callback gera um aviso _doing_it_wrong. Para um endpoint público, passe __return_true de forma explícita.
• Os namespaces devem seguir o padrão vendor/v1, e a versão sobe quando quebra a compatibilidade.
• Os erros são um WP_Error com o código HTTP definido na chave status dos seus dados, por exemplo 400 para dados de entrada inválidos.
• Quando envolve um callback existente, passe o valor devolvido por rest_ensure_response().

<?php
declare(strict_types=1);

class Wppoland_Metrics_Controller extends WP_REST_Controller
{
    protected $namespace = 'wppoland/v1';
    protected $rest_base = 'metrics';

    public function register_routes(): void
    {
        register_rest_route($this->namespace, '/' . $this->rest_base . '/(?P<id>\d+)', [
            [
                'methods' => WP_REST_Server::READABLE,
                'callback' => [$this, 'get_item'],
                'permission_callback' => '__return_true',
                'args' => [
                    'id' => ['type' => 'integer', 'required' => true],
                ],
            ],
            'schema' => [$this, 'get_public_item_schema'],
        ]);
    }

    public function get_item($request)
    {
        $post = get_post((int) $request['id']);
        if (!$post || $post->post_status !== 'publish') {
            return new WP_Error('rest_post_invalid_id', __('Conteúdo não encontrado.', 'wppoland'), ['status' => 404]);
        }
        return rest_ensure_response([
            'id' => $post->ID,
            'title' => get_the_title($post),
        ]);
    }

    public function get_item_schema(): array
    {
        return [
            '$schema' => 'http://json-schema.org/draft-04/schema#',
            'title' => 'wppoland_metrics',
            'type' => 'object',
            'properties' => [
                'id' => ['type' => 'integer'],
                'title' => ['type' => 'string'],
            ],
        ];
    }
}

add_action('rest_api_init', function (): void {
    (new Wppoland_Metrics_Controller())->register_routes();
});

As propriedades são declaradas sem tipo de propósito: o WP_REST_Controller declara $namespace e $rest_base sem tipo, e o PHP recusa uma redeclaração tipada numa classe filha. Para o percurso completo do controlador, consulte o nosso guia de endpoints personalizados da REST API.

#6. O GraphQL é mais rápido do que a REST API no WordPress

Em 2026, desempenho não é apenas velocidade, é eficiência.

• Latência de rede: o GraphQL ganha em páginas complexas. Ao agrupar vários dados num único pedido, elimina as idas e voltas sequenciais de que uma página REST com post, autor, termos e artigos relacionados precisa.
• Estratégia de cache: a REST ganha em facilidade. Como cada endpoint é um URL único, pode guardá-lo em cache globalmente na Cloudflare com pouco esforço. O GraphQL precisa de pedidos GET ou de persisted queries para obter resultados semelhantes de cache no Edge.
• CPU do servidor: a REST é normalmente mais leve para um único recurso simples. O GraphQL tem de analisar e validar o documento de query antes de resolver o que quer que seja, e é por isso que a cache de objetos pesa mais num site com GraphQL.

A equipa do WPGraphQL publicou uma medição: obter 100 posts custou 335 kb e 7,91 s a partir do endpoint REST, contra 6,4 kb e 67 ms a partir do WPGraphQL (WPGraphQL vs WP REST API). Trate isto como o teste do próprio fornecedor com a saída REST por omissão. Um pedido REST com _fields reduz grande parte da diferença de payload, por isso meça as suas próprias páginas antes de decidir apenas com base neste argumento.

#Testes comparativos da WPPoland

Para avaliar empiricamente o impacto de cada abordagem na experiência do utilizador final, a equipa de engenharia da WPPoland realizou testes comparativos rigorosos em cinco cenários representativos de um portal corporativo de alto tráfego:

#Custo do parsing de JSON em dispositivos móveis

Muitas equipas de desenvolvimento focam-se exclusivamente no tempo de transferência de rede, esquecendo o custo de processamento no dispositivo do cliente. Em smartphones de gama média e de entrada, o motor JavaScript (V8 / JavaScriptCore) necessita de analisar, desserializar e alocar em memória cada kilobyte de JSON recebido:

• Um payload REST de 150 KB contendo 80 campos redundantes pode consumir entre 15ms e 40ms de tempo de CPU da thread principal (Main Thread) apenas para a operação JSON.parse().
• O payload GraphQL otimizado de 24 KB é processado em menos de 3ms, libertando a thread principal do navegador para manter o índice de interatividade (INP) abaixo do limiar de 200 ms que a Google classifica como bom.

#7. Como fazer cache de GraphQL na CDN com persisted queries

As queries GraphQL são normalmente enviadas por HTTP POST com a query no corpo do pedido, e uma CDN não guarda POST em cache pelo URL. A orientação do próprio WPGraphQL é que POST é o método habitual e que GET tem suporte limitado (Interacting with WPGraphQL). A cache no Edge fica a cargo do plugin complementar WPGraphQL Smart Cache (versão 2.3.3, mais de 6.000 instalações ativas, agora parte do monorepo do WPGraphQL, segundo a sua página do plugin).

Como funciona, segundo a documentação do Smart Cache:

• Network cache: para tirar partido dela, envie pedidos HTTP GET para dados públicos. As respostas trazem um cabeçalho X-GraphQL-Keys com tags para tudo aquilo em que a query tocou. Quando o conteúdo muda, o Smart Cache envia eventos de purga e o alojamento remove os documentos em cache marcados com essas chaves. O guia indica a WP Engine e a Pantheon como alojamentos compatíveis. O max-age por omissão é de 600 segundos, ajustável nas definições de Cache do plugin (Network cache).
• Persisted queries: um documento de query é guardado no servidor num post type não público graphql_document e referenciado por um ID de query. O slug do documento é o hash SHA-256 da query, e um cliente só pode registar um novo queryId se este corresponder a esse hash. Os clientes enviam depois pedidos GET curtos, como ?queryId=getPostById&variables={...}. O plugin funciona com o Apollo Persisted Query Link (Persisted queries).
• Listas de permissão e de bloqueio: nas definições de queries guardadas, escolhe entre um endpoint totalmente público, permitir apenas queries guardadas específicas ou bloquear queries específicas. Os utilizadores com manage_options ficam isentos.

Com pedidos GET, persisted queries e purga por tags implementados, uma resposta GraphQL fica em cache no Edge de forma muito semelhante a um URL REST. Sem eles, a cache de GraphQL fica limitada à cache de objetos do WordPress.

#8. WordPress REST batch API vs. batching em GraphQL

O WordPress 5.6 introduziu uma framework de batch em /wp-json/batch/v1. Aceita um único POST com vários sub-pedidos, 25 por omissão (filtro rest_get_max_batch_size). Os pedidos GET não são suportados, pelo que se destina a escritas, e cada rota tem de aderir com allow_batch quando é registada. Um modo require-all-validate rejeita o lote inteiro se algum pedido falhar a validação (REST API batch framework in WordPress 5.6).

#Limitações do batching na REST API

1. Sem composição de dados: os sub-pedidos correm como operações separadas. Não é possível usar o resultado do pedido A (um ID de autor) no pedido B dentro do mesmo lote.
2. Orientado para escrita: sem GET, o endpoint de batch não ajuda em nada um frontend que sobretudo lê dados.
3. Sem cache no Edge: é um POST, por isso a CDN encaminha cada lote para a origem.

O GraphQL resolve dados relacionados dentro de uma única query por definição, e o WPGraphQL também aceita queries em lote. A sua documentação de segurança indica que pode limitar ou desativar as queries em lote na página de definições do GraphQL.

#9. Limites de paginação na REST API e no GraphQL

A REST API limita per_page a 100 registos e devolve dois cabeçalhos com cada coleção: X-WP-Total (total de registos) e X-WP-TotalPages (total de páginas) (Pagination). Um cliente que precise de 450 posts faz cinco pedidos.

O WPGraphQL usa connections baseadas em cursores (first, after, pageInfo { hasNextPage endCursor }). Limita os itens por página de connection a 100 na maioria das connections, e o filtro graphql_connection_max_query_amount altera esse limite (WPGraphQL security). Aumente-o apenas em conjunto com o limite de profundidade e a cache, porque páginas maiores tornam mais barato enviar queries dispendiosas.

#10. Autenticação na WordPress REST API e no WPGraphQL

A REST API tem dois métodos incorporados (Authentication):

• Autenticação por cookie, para código que corre no painel com sessão iniciada. Um pedido manual tem de enviar um nonce para a ação wp_rest, normalmente no cabeçalho X-WP-Nonce. Sem o nonce, o pedido é tratado como não autenticado, mesmo que o utilizador tenha sessão iniciada.
• Application Passwords, incluídas no core desde o WordPress 5.6. Usam Basic Auth e funcionam apenas sobre HTTPS.

O WPGraphQL segue as permissões do WordPress: tudo o que o WordPress expõe publicamente é público no GraphQL, e os dados que exigem autenticação no WordPress exigem um pedido GraphQL autenticado. Os utilizadores sem posts publicados ficam excluídos das queries públicas de utilizadores, e campos como o email de um utilizador exigem uma permissão específica (WPGraphQL security). Os fluxos de login baseados em tokens (JWT e semelhantes) vêm de extensões, não do plugin principal.

#11. Como proteger a REST API e o GraphQL no WordPress

Fontes: WPGraphQL security, REST API Handbook FAQ. A forma indicada pelo handbook para bloquear o acesso anónimo à REST é uma verificação is_user_logged_in() no filtro rest_authentication_errors. O rate limiting pertence ao Edge (WAF ou CDN) para ambas as APIs, porque nem o plugin nem o core o incluem.

#12. Gerar tipos TypeScript a partir do WPGraphQL

Como o schema GraphQL é tipado e permite introspection, ferramentas como o GraphQL Code Generator conseguem ler o schema e as queries do frontend e gerar tipos TypeScript para cada resultado de query. Um campo que passa a aceitar null ou desaparece do schema falha então a verificação de tipos no editor e na CI, antes de chegar à produção.

import type { TypedDocumentNode } from '@graphql-typed-document-node/core';
import { print } from 'graphql';

export async function executeGraphQL<TData, TVariables>(
  document: TypedDocumentNode<TData, TVariables>,
  variables?: TVariables
): Promise<TData> {
  const response = await fetch(import.meta.env.WP_GRAPHQL_ENDPOINT, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ query: print(document), variables }),
  });
  if (!response.ok) throw new Error(`GraphQL HTTP ${response.status}`);
  const { data, errors } = await response.json();
  if (errors?.length) throw new Error(errors[0].message);
  return data;
}

A REST API publica um JSON Schema para cada rota, por isso também aí é possível gerar tipos, mas monta-os endpoint a endpoint e o servidor não valida a seleção de campos do seu cliente.

#13. Tratamento de erros na REST API e no GraphQL

Um erro REST é um WP_Error serializado como JSON com code, message e data.status, e o estado HTTP da resposta corresponde a data.status. Se o pedido falhar, a resposta inteira é um erro. É previsível para a monitorização, mas uma página construída a partir de uma única chamada REST não consegue renderizar metade dos seus dados.

O GraphQL pode devolver dados parciais. A resposta traz data e errors, e cada erro tem um path que aponta para o campo que falhou:

{
  "data": { "post": { "title": "Arquitetura headless WordPress", "relatedPosts": null } },
  "errors": [
    { "message": "Internal server error", "path": ["post", "relatedPosts"] }
  ]
}

O frontend pode renderizar o artigo e mostrar um fallback apenas para o bloco que falhou. O reverso: um pedido GraphQL que falhou parcialmente continua a devolver HTTP 200, por isso a monitorização tem de ler o array errors e não apenas os códigos de estado.

#14. Mutations GraphQL e optimistic UI no WordPress

No GraphQL, as escritas são mutations. Uma mutation altera dados e devolve o objeto atualizado na mesma resposta, por isso o cliente pode atualizar o seu estado local sem um segundo pedido. O WPGraphQL inclui de base mutations para posts, termos, utilizadores e comentários, por exemplo createComment:

mutation AddComment($input: CreateCommentInput!) {
  createComment(input: $input) {
    success
    comment { id content date }
  }
}

Isto torna a optimistic UI simples: a interface mostra o novo comentário de imediato e só reverte se a mutation devolver um erro. As mutations de carrinho do WooCommerce não fazem parte do WPGraphQL base; vêm de uma extensão separada. Com REST, o mesmo fluxo é um POST seguido da leitura do recurso devolvido, o que funciona igualmente bem para escritas isoladas.

#15. GraphQL ou REST para agentes de IA e a Abilities API

Os agentes de IA e os clientes MCP são hoje consumidores regulares de APIs. A introspection do GraphQL permite a um agente ler o schema e ver que tipos e argumentos existem, mas o WPGraphQL mantém a introspection pública desativada por omissão, pelo que um agente precisa de acesso autenticado ou de um schema exportado.

O core do WordPress seguiu outro caminho. A Abilities API, no core desde o WordPress 6.9 (2 de dezembro de 2025), regista operações com um schema de entrada e de saída, um callback de permissões e um callback de execução, e expõe-nas através dos endpoints REST wp-abilities/v1 e do MCP Adapter (Abilities API in WordPress 6.9). Para agentes que atuam sobre um site, esta camada baseada em REST é o caminho nativo. Mais detalhes no nosso guia da WordPress Abilities API.

#16. Testar APIs WordPress com GraphiQL e Postman

• REST: familiar para quase todos os programadores. Pode testar endpoints de imediato no navegador ou em ferramentas como o Postman. Acrescente ?_envelope quando um cliente não consegue ler cabeçalhos: a resposta passa a trazer os cabeçalhos e o código de estado no corpo.
• GraphQL: o WPGraphQL inclui o GraphiQL, um IDE no navegador dentro do painel do WordPress que permite percorrer todo o schema, ver os campos disponíveis e testar queries e mutations com preenchimento automático. Para equipas de frontend, é um ganho real de produtividade.

Para evitar regressões, compare as queries do frontend com o schema na CI a cada merge, de modo que um campo removido ou com tipo alterado faça falhar o build. Do lado da REST, valide as respostas contra o JSON Schema de cada rota.

#17. Como migrar da REST API para o WPGraphQL sem downtime

1. Coexistência: instale o WPGraphQL em staging com wp plugin install wp-graphql --activate e mapeie cada custom post type e taxonomia no schema. A REST continua a servir a produção.
2. Primeiro as páginas só de leitura: passe as páginas de arquivo e de listagem para queries GraphQL, com tipos gerados, e compare o payload e o tempo de resposta com a versão REST.
3. Páginas de detalhe e cache: passe as vistas individuais e depois acrescente o Smart Cache com pedidos GET ou persisted queries, se o seu alojamento suportar network cache.
4. Limpar a exposição da REST: mantenha as rotas REST usadas por webhooks, automatizações e integrações, e exija autenticação onde já não exista nenhum consumidor público.

#18. Tabela comparativa REST vs. GraphQL

#Desenvolvimento de APIs WordPress com a WPPoland

Na WPPoland, somos especialistas no desenho, implementação e otimização de camadas de API de alto rendimento para o ecossistema WordPress corporativo.

Os nossos serviços especializados de engenharia incluem:

1. Modelação de Esquemas de Dados Estritos: Estruturamos os seus tipos de dados, resolvers e DataLoaders para garantir máxima velocidade de resposta.
2. Desenvolvimento de Frontends Modernos: Integramos o seu WordPress com Astro e Next.js.
3. Hardening e Proteção WAF: Blindamos os seus endpoints contra abusos com regras avançadas de limitação de taxa e autenticação baseada em chaves criptográficas.
4. Otimização de Base de Dados e Cache Redis: Implementamos cache de objetos com Redis para eliminar contenção no MySQL.

Explore a nossa gama de serviços de desenvolvimento personalizado WordPress e fale connosco para planear a sua estratégia de migração para Astro e Next.js.

#Quando usar GraphQL em vez de REST no WordPress

Se está a construir um site moderno e desacoplado com React, Astro ou Next.js, o GraphQL é normalmente a melhor opção. A possibilidade de pedir exatamente o que é necessário, com tipos gerados, resulta num frontend mais leve e mais fácil de manter.

No entanto, não ignore a REST. Para integrações simples, aplicações móveis que só precisam de um feed de posts, automatização interna, webhooks e agentes de IA que usam a Abilities API, a REST API nativa continua a ser a forma mais rápida de concluir o trabalho, sem nenhum plugin para manter. Muitos sites em produção usam ambas: GraphQL para o frontend público, REST para as integrações.

Saiba mais sobre a migração de sites para Astro e Next.js com a WPPoland.

Ainda está a obter o objeto completo do post só para mostrar um título? Acrescente _fields hoje e planeie a passagem para GraphQL quando o frontend o justificar.