Assinar

O que você está procurando?

Aperte Enter para buscar ou ESC para fechar

Rest API

A REST API do WordPress é uma interface que permite que aplicações leiam, criem, atualizem e excluam dados de um site WordPress por meio de requisições HTTP.

Na prática, ela permite acessar conteúdos e funcionalidades do WordPress sem precisar carregar uma página tradicional do site ou executar diretamente código PHP dentro dele.

Posts, páginas, usuários, comentários, taxonomias, mídias e vários outros recursos podem ser disponibilizados por URLs específicas chamadas rotas, recebendo e retornando dados principalmente no formato JSON.

É uma das tecnologias fundamentais para transformar o WordPress de um sistema que apenas gera páginas HTML em uma plataforma capaz de funcionar também como backend para outras aplicações.

O que significa REST API?

API significa Application Programming Interface, ou Interface de Programação de Aplicações.

Uma API define uma maneira estruturada para que dois sistemas se comuniquem.

REST significa Representational State Transfer e descreve um conjunto de princípios arquiteturais para representar e manipular recursos através da Web. Na REST API do WordPress, esses recursos podem ser posts, páginas, usuários, comentários, termos, mídias ou recursos criados por plugins e desenvolvedores.

Um aplicativo não precisa saber como o WordPress armazena um post no banco de dados, quais tabelas são utilizadas ou quais funções PHP precisam ser executadas.

Ele pode simplesmente fazer uma requisição para:

https://exemplo.com/wp-json/wp/v2/posts/123

E receber uma representação daquele post.

Essa separação é uma das ideias fundamentais de uma API.

O consumidor conhece o contrato da interface, mas não precisa conhecer a implementação interna.

A REST API faz parte do WordPress?

Sim. A infraestrutura da REST API entrou no WordPress Core na versão 4.4. Posteriormente, no WordPress 4.7, foram incorporados os principais endpoints de conteúdo, permitindo acesso padronizado a posts, páginas, comentários, usuários, termos e outros tipos de dados do WordPress.

Portanto, não é necessário instalar um plugin para ter acesso à REST API básica.

Em uma instalação comum com permalinks habilitados, seu ponto inicial normalmente pode ser acessado em:

https://exemplo.com/wp-json/

Essa URL retorna o índice da API, incluindo informações sobre namespaces, rotas e endpoints disponíveis naquela instalação.

Plugins também podem adicionar suas próprias APIs a essa estrutura.

Por isso, duas instalações WordPress podem possuir conjuntos diferentes de endpoints dependendo dos plugins e funcionalidades instalados.

Recursos: o que estamos manipulando?

REST é uma arquitetura orientada a recursos.

Um post é um recurso. Um usuário é um recurso. Uma categoria é um recurso. Uma imagem da biblioteca de mídia é um recurso.

Esses recursos são representados por URLs.

Por exemplo:

/wp-json/wp/v2/posts

representa a coleção de posts.

Já:

/wp-json/wp/v2/posts/123

representa especificamente o post cujo ID é 123.

Da mesma forma:

/wp-json/wp/v2/users

representa usuários, enquanto:

/wp-json/wp/v2/categories

representa categorias.

É importante perceber que essas URLs não representam necessariamente arquivos físicos no servidor.

Elas são rotas que o WordPress interpreta e direciona para código responsável por processar aquela requisição.

Rotas e endpoints não são exatamente a mesma coisa

No vocabulário da REST API do WordPress existe uma diferença técnica entre route e endpoint.

Uma rota identifica o caminho de um recurso.

Por exemplo:

/wp/v2/posts/123

Já um endpoint representa uma determinada combinação entre essa rota e uma operação HTTP.

A mesma rota pode aceitar:

GET /wp/v2/posts/123

para consultar o post;

POST /wp/v2/posts/123

para modificá-lo;

e:

DELETE /wp/v2/posts/123

para excluí-lo.

Portanto, tecnicamente, a rota continua sendo /wp/v2/posts/123, mas existem diferentes endpoints associados a ela, dependendo do método HTTP utilizado.

No uso cotidiano, entretanto, é bastante comum que os dois termos sejam utilizados de maneira menos rigorosa.

O que são wp-json, wp e v2?

Observe esta URL:

https://exemplo.com/wp-json/wp/v2/posts

Ela pode ser dividida em algumas partes.

wp-json é normalmente o caminho base através do qual acessamos a REST API.

wp/v2 é o namespace utilizado pelos endpoints do WordPress Core.

posts é o recurso que queremos acessar.

Namespaces são importantes porque impedem conflitos entre diferentes APIs.

Um plugin chamado minha-loja, por exemplo, poderia registrar:

/wp-json/minha-loja/v1/produtos

Enquanto outro plugin poderia utilizar:

/wp-json/outro-plugin/v1/produtos

Mesmo que ambos possuam uma rota chamada produtos, elas pertencem a namespaces diferentes.

O número da versão também possibilita que uma API evolua mantendo compatibilidade com integrações antigas.

Os métodos HTTP definem a operação

REST aproveita os próprios métodos do protocolo HTTP para indicar o que deve acontecer com um recurso.

MétodoUso comum
GETConsultar um recurso
POSTCriar ou atualizar dados
PUTAtualizar um recurso
DELETEExcluir um recurso
OPTIONSConsultar informações e capacidades de um endpoint

Uma requisição:

GET /wp-json/wp/v2/posts

consulta posts.

Enquanto uma requisição autenticada:

POST /wp-json/wp/v2/posts

pode criar um novo post.

A URL pode ser praticamente a mesma, mas o método HTTP muda completamente o significado da operação.

Como uma requisição é processada pelo WordPress?

Quando uma requisição chega à REST API, o WordPress identifica a rota solicitada e procura um endpoint compatível com o método HTTP utilizado.

Internamente, a requisição é representada por um objeto da classe:

WP_REST_Request

Esse objeto reúne informações como rota, método HTTP, headers, parâmetros da URL e dados enviados no corpo da requisição.

Depois da autenticação e das verificações de permissão, o WordPress encaminha essa requisição para o callback ou controller responsável pelo endpoint.

O código executa a operação necessária e devolve uma resposta.

A API possui estruturas próprias para isso, principalmente:

WP_REST_Response

e:

WP_Error

Assim, o cliente recebe tanto os dados quanto informações HTTP sobre o resultado da operação.

A REST API utiliza JSON

A REST API do WordPress utiliza JSON — JavaScript Object Notation — como formato de representação dos dados.

Uma requisição como:

GET /wp-json/wp/v2/posts/123

poderia retornar algo semelhante a:

{
  "id": 123,
  "date": "2026-10-15T10:30:00",
  "slug": "meu-artigo",
  "status": "publish",
  "link": "https://exemplo.com/meu-artigo/",
  "title": {
    "rendered": "Meu artigo"
  },
  "content": {
    "rendered": "<p>Conteúdo do artigo...</p>"
  }
}

O frontend pode interpretar esses dados e decidir como apresentá-los.

Ele não precisa utilizar PHP e nem mesmo precisa estar hospedado no mesmo servidor que o WordPress.

Pode ser uma aplicação React, um aplicativo para celular, um sistema escrito em Python, uma aplicação desktop ou praticamente qualquer software capaz de fazer requisições HTTP e interpretar JSON.

É justamente isso que permite utilizar WordPress como um headless CMS.

Coleções e itens individuais

Boa parte dos endpoints da REST API segue uma estrutura de coleções e itens.

Por exemplo:

GET /wp-json/wp/v2/posts

retorna uma coleção de posts.

Enquanto:

GET /wp-json/wp/v2/posts/123

solicita apenas um post específico.

Coleções normalmente suportam parâmetros para controlar filtros, paginação e ordenação.

Por exemplo:

/wp-json/wp/v2/posts?per_page=5

solicita cinco posts.

Também podemos combinar diferentes parâmetros dependendo do endpoint.

Essa estrutura torna as URLs relativamente previsíveis para quem já conhece APIs REST.

É possível escolher quais campos serão retornados?

Sim.

Um recurso particularmente importante da REST API do WordPress é o parâmetro global:

_fields

Imagine que uma aplicação esteja criando apenas uma lista de artigos e necessite somente do ID, título e link.

Não seria necessário receber todo o conteúdo do post.

Podemos solicitar:

/wp-json/wp/v2/posts?_fields=id,title,link

Assim, a resposta contém apenas os campos necessários.

Isso reduz o tamanho do JSON e pode também impedir processamento desnecessário durante a criação da resposta.

Esse recurso é particularmente importante quando comparamos REST com tecnologias como GraphQL, porque a ideia de que uma REST API obrigatoriamente precisa retornar todos os campos de um recurso não é correta no caso da API do WordPress.

E os relacionamentos entre os dados?

Um post pode possuir um autor, uma imagem destacada, categorias e tags.

Por padrão, alguns desses relacionamentos aparecem na resposta apenas através de seus identificadores ou links.

A REST API possui mecanismos de linking e embedding para trabalhar com essas relações.

Um parâmetro particularmente útil é:

_embed

Por exemplo:

/wp-json/wp/v2/posts?_embed

pode fazer com que determinados recursos relacionados sejam incorporados diretamente à resposta.

Também podemos solicitar relações específicas.

Isso pode diminuir a necessidade de múltiplas requisições HTTP para montar uma interface.

É uma funcionalidade importante porque REST não significa necessariamente que cada relacionamento precise resultar em uma nova requisição independente.

A API pública não significa que tudo no WordPress seja público

A existência da REST API não significa que qualquer pessoa pode modificar o site.

Algumas informações públicas podem ser consultadas sem autenticação, exatamente como alguém poderia acessá-las através das páginas públicas do próprio site.

Operações sensíveis dependem de autenticação e de permissões.

Por exemplo, para editar um post, não basta conhecer sua URL REST.

O usuário autenticado precisa possuir a capability necessária para realizar aquela operação.

A API utiliza o próprio sistema de usuários, roles e capabilities do WordPress.

Como funciona a autenticação?

Quando a REST API é utilizada dentro do próprio WordPress por um usuário autenticado, o método padrão é baseado nos cookies de autenticação do WordPress.

Para proteger essas requisições contra ataques como CSRF, o WordPress também utiliza nonces REST, normalmente enviados através do header:

X-WP-Nonce

O nonce utilizado nesse contexto é criado com a ação:

wp_rest

Esse modelo baseado em cookies é especialmente adequado para requisições feitas dentro do contexto do próprio WordPress.

Para aplicações externas, o WordPress possui Application Passwords desde a versão 5.6.

Uma Application Password é uma credencial separada vinculada a um usuário e destinada especificamente ao acesso programático. Ela pode ser revogada individualmente sem alterar a senha principal daquela conta.

Uma aplicação externa poderia fazer, por exemplo:

curl --user "usuario:SENHA_DA_APLICACAO" \
https://exemplo.com/wp-json/wp/v2/users/me

Como essas credenciais são normalmente transportadas através de HTTP Basic Authentication, a conexão deve utilizar HTTPS.

Plugins também podem implementar outros mecanismos de autenticação quando necessário.

Autenticação e autorização são coisas diferentes

É importante diferenciar os dois conceitos.

Autenticação responde:

Quem está fazendo a requisição?

Já autorização responde:

Essa pessoa pode executar esta operação?

Um usuário pode estar perfeitamente autenticado e ainda assim não possuir permissão para editar determinado conteúdo.

É por isso que endpoints personalizados precisam fazer verificações de permissão adequadas.

A REST API não deve ser tratada como uma maneira de contornar o sistema de segurança do WordPress, mas como outra interface através da qual esse sistema pode ser utilizado.

Plugins podem criar seus próprios endpoints

A REST API é extensível.

Um plugin pode registrar uma nova rota utilizando:

register_rest_route()

O registro normalmente acontece durante a action:

rest_api_init

A própria documentação do WordPress recomenda utilizar namespaces próprios para evitar conflitos entre plugins.

Um exemplo bastante simplificado seria:

add_action(
    'rest_api_init',
    function () {
        register_rest_route(
            'meu-plugin/v1',
            '/status',
            [
                'methods'             => 'GET',
                'callback'            => function () {
                    return rest_ensure_response(
                        [
                            'status' => 'ok',
                        ]
                    );
                },
                'permission_callback' => '__return_true',
            ]
        );
    }
);

Isso disponibilizaria:

GET /wp-json/meu-plugin/v1/status

e retornaria:

{
  "status": "ok"
}

Nesse exemplo, __return_true torna intencionalmente o endpoint público.

Em um endpoint que acessasse informações privadas ou executasse alguma alteração no site, o permission_callback deveria verificar a capacidade do usuário.

Por exemplo:

'permission_callback' => function () {
    return current_user_can( 'manage_options' );
}

Esse detalhe é fundamental.

Criar um endpoint REST não significa apenas registrar uma URL: o desenvolvedor também precisa definir corretamente quem pode executar aquela operação.

O que é o schema da REST API?

A REST API do WordPress também possui suporte a JSON Schema.

O schema descreve a estrutura esperada dos dados.

Ele pode indicar, por exemplo, que determinado campo:

title

é uma string;

que:

id

é um inteiro;

ou que determinado parâmetro é obrigatório.

O WordPress consegue utilizar essas definições para validação e sanitização dos dados recebidos, além de melhorar a capacidade de descoberta e documentação da API.

Para endpoints personalizados mais complexos, definir schemas ajuda a transformar a API em um contrato mais previsível entre servidor e consumidor.

Controllers organizam endpoints mais complexos

O WordPress também possui uma arquitetura baseada em classes derivadas de:

WP_REST_Controller

Controllers podem centralizar a lógica de um determinado recurso, incluindo registro das rotas, recuperação de coleções, recuperação de itens individuais, criação, atualização, exclusão, preparação de respostas e definição de schema.

É o padrão utilizado internamente por diversos endpoints do próprio WordPress.

Para uma rota muito simples, um callback pode ser suficiente.

Para uma API complexa mantida por um plugin, utilizar controllers geralmente produz uma arquitetura mais organizada.

A REST API é utilizada pelo próprio WordPress

É comum pensar na REST API apenas como uma ferramenta para conectar WordPress com sistemas externos.

Esse é um dos usos, mas não o único.

O próprio WordPress utiliza sua infraestrutura REST em interfaces modernas da administração. Funcionalidades do Editor de blocos, por exemplo, dependem da REST API para consultar e manipular determinados dados.

Isso muda bastante a maneira como devemos enxergar a tecnologia.

A REST API não é apenas uma integração opcional instalada ao lado do WordPress.

Ela faz parte da infraestrutura atual da plataforma.

REST API não é a mesma coisa que WordPress HTTP API

Os nomes podem causar confusão, mas são tecnologias diferentes.

A REST API disponibiliza dados e operações do seu WordPress para consumidores através de endpoints HTTP.

Já a WordPress HTTP API é o conjunto de funções que o WordPress oferece para fazer requisições HTTP para outros servidores.

Por exemplo:

wp_remote_get()

pertence à HTTP API.

Enquanto:

/wp-json/wp/v2/posts

pertence à REST API.

Uma é utilizada principalmente para o WordPress fazer requisições.

A outra permite que aplicações façam requisições ao WordPress.

As duas podem, inclusive, ser utilizadas juntas.

REST API também não é simplesmente uma substituta para admin-ajax.php

Antes da REST API, muitos plugins WordPress utilizavam:

/wp-admin/admin-ajax.php

como principal maneira de comunicação assíncrona entre JavaScript e PHP.

Esse mecanismo continua existindo e ainda possui casos de uso legítimos.

Mas uma API REST oferece uma arquitetura muito mais estruturada quando estamos expondo recursos e operações que precisam ser consumidos por aplicações.

Em vez de concentrar diferentes operações em uma única URL controlada pelo parâmetro action, REST permite modelar recursos através de rotas, métodos HTTP, schemas, callbacks de permissões e respostas padronizadas.

Por isso, para novas APIs de plugins, utilizar a infraestrutura REST normalmente produz uma interface mais clara e reutilizável.

Para que a REST API do WordPress pode ser utilizada?

A REST API permite que WordPress participe de arquiteturas que vão muito além de um tema PHP tradicional.

Ela pode servir dados para aplicações headless, aplicativos móveis, dashboards, ferramentas de automação, integrações com sistemas externos, interfaces JavaScript, serviços de sincronização e funcionalidades desenvolvidas por plugins.

Mas talvez sua característica mais importante seja a separação que cria entre dados e apresentação.

O WordPress pode continuar responsável por usuários, permissões, conteúdo, taxonomias, mídia e regras de negócio enquanto outra aplicação decide como esses dados serão apresentados.

É justamente essa separação que tornou a REST API uma peça importante na evolução do WordPress de um CMS tradicional para uma plataforma capaz de atuar também como backend de aplicações.

Em resumo

A REST API do WordPress é uma interface HTTP nativa que representa recursos do WordPress através de rotas e permite manipulá-los utilizando métodos como GET, POST e DELETE.

Ela recebe e retorna dados em JSON, utiliza o sistema de autenticação e capabilities do próprio WordPress, suporta schemas, relacionamentos, filtros e paginação e pode ser expandida por plugins através de endpoints personalizados.

Uma requisição como:

GET /wp-json/wp/v2/posts

parece simples.

Mas por trás dela existe uma infraestrutura que separa a aplicação que consome os dados da maneira como esses dados estão armazenados e processados internamente.

É essa separação que torna a REST API importante não apenas para integrações externas, mas para a própria arquitetura moderna do WordPress.

Fontes e referências