Guia da WordPress REST API

O que é a WordPress REST API

A REST API do ecossistema WordPress é uma interface que permite a aplicações externas comunicar com um site WordPress através de pedidos HTTP. Em vez de aceder ao conteúdo através do frontend do WordPress ou do painel de administração, a REST API permite ler, criar, atualizar e eliminar conteúdo de forma programática, utilizando métodos HTTP standard (GET, POST, PUT, DELETE) e o formato JSON para a troca de dados.

A REST API está integrada no WordPress desde a versão 4.7 (dezembro de 2016) e representa a forma moderna de interagir com o WordPress. É utilizada por aplicações móveis que apresentam conteúdo WordPress, frontends em JavaScript (React, Vue, Angular) que usam o WordPress como backend, integrações com serviços externos e automação da gestão de conteúdos. O editor Gutenberg, o editor standard do WordPress desde a versão 5.0, utiliza intensivamente a REST API para todas as operações de conteúdo. Se está apenas a começar, consulte o nosso guia de instalação do WordPress.

Fundamentos da REST API

Endpoints e rotas

A WordPress REST API está disponível no seu site no caminho /wp-json/. Utilizando um browser ou uma ferramenta como o cURL ou o Postman, pode aceder à API. Por exemplo, um pedido GET a /wp-json/wp/v2/posts devolve uma lista de publicações em formato JSON, /wp-json/wp/v2/pages devolve páginas, /wp-json/wp/v2/categories devolve categorias, /wp-json/wp/v2/users devolve utilizadores, /wp-json/wp/v2/media devolve ficheiros multimédia e /wp-json/wp/v2/comments devolve comentários. Cada um destes endpoints suporta diferentes métodos HTTP para diferentes operações — GET para leitura, POST para criação, PUT/PATCH para atualização e DELETE para eliminação.

Parâmetros de consulta

A REST API suporta numerosos parâmetros para filtrar e paginar resultados. O parâmetro per_page controla o número de resultados por página (predefinição 10, máximo 100), page especifica a página de resultados para a paginação, search pesquisa conteúdo por palavra-chave, orderby define o campo de ordenação (date, title, id), order define a direção da ordenação (asc ou desc) e categories e tags filtram por categoria ou etiqueta. Por exemplo, o pedido /wp-json/wp/v2/posts?per_page=5&categories=3&orderby=date&order=desc devolve as 5 publicações mais recentes da categoria com o ID 3.

Estrutura da resposta

A API devolve dados em formato JSON. Cada objeto de publicação contém id (identificador único), title com a propriedade rendered (título com formatação HTML), content com a propriedade rendered (conteúdo da publicação), excerpt com a propriedade rendered (extrato), date (data de publicação no formato ISO 8601), slug (título amigável para URL), status (publish, draft, pending), author (ID do autor), categories e tags (arrays de IDs). Os cabeçalhos da resposta HTTP contêm metadados úteis: X-WP-Total (número total de itens) e X-WP-TotalPages (número total de páginas).

Autenticação

Endpoints públicos vs protegidos

Alguns endpoints estão disponíveis publicamente sem autenticação — leitura de publicações publicadas, páginas, categorias e etiquetas. As operações que modificam dados (criar, atualizar, eliminar) e o acesso a dados privados exigem autenticação. A WordPress REST API suporta vários métodos de autenticação consoante o contexto de utilização.

Application Passwords

Desde o WordPress 5.6, as Application Passwords estão integradas no núcleo e representam a forma mais simples de autenticar aplicações externas. Cria uma Application Password para um utilizador em Utilizadores → Perfil → Application Passwords. A palavra-passe gerada é utilizada com HTTP Basic Authentication — envia o nome de utilizador e a application password no cabeçalho Authorization de cada pedido. As Application Passwords têm a vantagem de poderem ser revogadas individualmente sem alterar a palavra-passe principal do utilizador.

Autenticação JWT

O JSON Web Token (JWT) é um método de autenticação popular em aplicações single-page e aplicações móveis. O WordPress não tem suporte JWT integrado, mas plugins como o JWT Authentication for WP REST API ou o Simple JWT Login adicionam esta funcionalidade. O cliente envia o nome de utilizador e a palavra-passe para o endpoint de token, obtém um token JWT e, em seguida, envia-o no cabeçalho Authorization como um Bearer token em cada pedido. Os tokens JWT têm um tempo de vida limitado e podem ser renovados sem reenviar a palavra-passe.

OAuth 2.0

O OAuth 2.0 é o standard da indústria para autorização que permite a terceiros aceder a recursos sem partilhar palavras-passe. O WordPress suporta OAuth através do plugin OAuth Server. O OAuth é ideal para aplicações que acedem a conteúdo WordPress em nome de um utilizador — o utilizador autoriza a aplicação através da página de login do WordPress, a aplicação recebe um access token e utiliza-o para as chamadas à API. Este é o método mais seguro para aplicações em produção.

Criar endpoints personalizados

Registar REST Route

O WordPress permite criar endpoints de API personalizados para as necessidades específicas da sua aplicação. Utilize a função register_rest_route() no hook rest_api_init. Define o namespace (por exemplo, myplugin/v1), a rota (por exemplo, /featured-posts), o método HTTP (GET, POST), uma função de callback que devolve dados e uma função permission_callback opcional para o controlo de acesso. Os endpoints personalizados são úteis para dados que exigem consultas complexas, agregações ou transformações que os endpoints standard não suportam.

Permission Callback

A função permission callback controla quem pode aceder ao endpoint. Para endpoints públicos, utilize __return_true. Para endpoints protegidos, verifique as permissões do utilizador através da função current_user_can(). Por exemplo, um endpoint para criar publicações deve verificar current_user_can('publish_posts'). Nunca deixe endpoints de escrita sem um permission callback, porque isso abre o site ao abuso.

Validação e sanitização de parâmetros

Os endpoints personalizados devem definir argumentos com validação e sanitização. Para cada parâmetro define required (se é obrigatório), type (string, integer, boolean), validate_callback (função que verifica a validade do valor) e sanitize_callback (função que limpa o valor antes de o usar). O WordPress oferece funções de sanitização integradas como sanitize_text_field(), absint() e sanitize_email(). Uma validação adequada previne erros inesperados e vulnerabilidades de segurança.

Headless WordPress

O conceito de CMS headless

O headless WordPress é uma arquitetura em que o WordPress é utilizado apenas como backend (CMS) para a gestão de conteúdos, enquanto a apresentação no frontend corre numa aplicação completamente separada. A WordPress REST API serve de ponte entre o backend e o frontend. O frontend pode ser construído em React, Vue.js, Next.js, Nuxt, Angular ou qualquer outra framework. As vantagens são o controlo total do frontend, melhor desempenho (páginas estáticas em vez da renderização PHP do WordPress), a possibilidade de utilizar o mesmo conteúdo num site, numa aplicação móvel e noutras plataformas, e uma experiência de desenvolvimento moderna (hot reloading, arquitetura baseada em componentes).

Next.js e WordPress

A combinação de Next.js e WordPress é uma das implementações headless mais populares. O Next.js proporciona server-side rendering (SSR), static site generation (SSG) e incremental static regeneration (ISR), resultando em sites extremamente rápidos. O conteúdo é obtido a partir da WordPress REST API durante a build (para SSG) ou a pedido (para SSR). O componente Image do Next.js otimiza automaticamente as imagens e o sistema de routing mapeia os slugs do WordPress para páginas. Muitos sites de grande dimensão utilizam esta combinação para as secções de blog, enquanto o resto do site usa componentes personalizados.

Desafios do headless

O headless WordPress não está isento de desafios. Perde os temas do WordPress e o customizer visual — tudo tem de ser programado na framework de frontend. Plugins que geram output no frontend (formulários de contacto, galerias, page builders) não funcionam em modo headless. A funcionalidade de pré-visualização exige configuração adicional. Plugins de SEO como o Yoast geram metadados, mas o frontend tem de os obter e apresentar corretamente. Comentários, pesquisa e paginação têm de ser implementados no frontend através de chamadas à API. A abordagem headless exige uma equipa com experiência em desenvolvimento frontend.

Segurança da REST API

Restringir o acesso

Por predefinição, a WordPress REST API está disponível publicamente e revela informação sobre utilizadores, publicações e estrutura do site. Para um site que não utiliza a API, considere restringir o acesso. Pode desativar a REST API para utilizadores não autenticados utilizando o filtro rest_authentication_errors, bloquear endpoints específicos (sobretudo /wp/v2/users, que revela nomes de utilizador) ou usar um plugin como o Disable WP REST API para uma desativação seletiva. Nunca bloqueie a REST API por completo se utilizar o editor Gutenberg, porque ele depende da API.

Rate Limiting

Uma REST API sem rate limiting pode ser abusada para ataques de força bruta, scraping de conteúdo ou DDoS. Implemente rate limiting ao nível do servidor web (módulo limit_req do Nginx, mod_ratelimit do Apache) ou através de regras de WAF. O Cloudflare Rate Limiting é uma solução simples — limite o endpoint /wp-json/ a um número razoável de pedidos por minuto (por exemplo, 60 para utilizadores autenticados, 30 para não autenticados).

Ferramentas úteis para trabalhar com a REST API

• Postman: Uma ferramenta gráfica para testar chamadas à API com suporte para todos os métodos HTTP, autenticação e coleções de pedidos.
• cURL: Uma ferramenta de linha de comandos para pedidos HTTP — ideal para testes rápidos e scripting.
• Insomnia: Uma alternativa moderna ao Postman com uma interface limpa e suporte para GraphQL.
• WP-CLI: A ferramenta de linha de comandos do WordPress que utiliza internamente a REST API e permite gerir o site a partir do terminal.
• Thunder Client: Uma extensão do VS Code para testar APIs diretamente a partir do editor.

Conclusão

A WordPress REST API abre novas possibilidades de utilização do WordPress para além do blog ou site tradicional. Quer esteja a criar uma aplicação móvel, um frontend em JavaScript ou a integrar o WordPress com outros sistemas, a REST API proporciona uma forma padronizada e documentada de aceder ao conteúdo. Para projetos headless, a combinação do WordPress com uma framework de frontend moderna como o Next.js oferece o melhor dos dois mundos — gestão de conteúdo simples e desempenho de topo. Na BeoHosting, todos os planos de alojamento WordPress suportam a REST API com configurações otimizadas de PHP e MySQL para respostas de API mais rápidas.