Primeiros passos com a REST API

Este texto foi traduzido usando IA. Se você deseja ver o texto original em inglês, clique aqui.

A REST API do WordPress.com permite que você visualize, crie ou edite conteúdo em qualquer site WordPress.com, bem como em qualquer site auto-hospedado (WordPress.org) conectado via Jetpack. Isso inclui não apenas posts do blog e páginas, mas também comentários, tags, categorias, mídia, estatísticas do site, notificações, opções de compartilhamento, perfis de usuário e muitos outros recursos do WordPress.com.

Algumas requisições (por exemplo, listar posts públicos) não precisam ser autenticadas, mas qualquer ação que exigiria que um usuário tivesse efetuado login (como criar um post) requer um token de autenticação.

Para fazer requisições autenticadas, primeiro você precisará criar uma conta no WordPress.com, caso ainda não tenha uma.

Como Usar

Existem duas formas de explorar os endpoints disponíveis na REST API do WordPress.com:

• A página de documentação de referência da REST API lista os endpoints disponíveis e detalha a entrada e saída de cada um, junto com exemplos de código em curl e PHP.
• O console de desenvolvimento da REST API permite que você construa e teste requisições reais à API.

Fazer requisições não autenticadas é simples. Como não são necessários cabeçalhos especiais, você pode até abrir esta URL no seu navegador para ver o que ela retorna: https://public-api.wordpress.com/rest/v1.1/sites/en.blog.wordpress.com/posts/?number=2&pretty=true

Fazer requisições autenticadas requer alguns passos adicionais. Todas as requisições autenticadas à REST API do WordPress.com exigem um token de acesso OAuth2. Esse token deve ser obtido nos endpoints OAuth2 do WordPress.com e pode ser adquirido por meio de diferentes fluxos, sendo os mais relevantes:

1. Full OAuth2 Flow – Os usuários autorizam seu aplicativo por meio da interface do WordPress.com, concedendo permissões específicas. Esta é a abordagem mais segura e obrigatória para aplicativos de terceiros.
2. Credentials Direct Token Exchange – Use uma Senha de Aplicativo com grant_type=password para obter diretamente um token para seus próprios sites. Isso ignora a etapa de autorização do usuário, mas requer suas credenciais do WordPress.com.

Ambos os métodos resultam no mesmo tipo de token de acesso OAuth2, que você inclui nas requisições como Authorization: Bearer YOUR_ACCESS_TOKEN. A abordagem baseada em tokens garante segurança consistente e permite controle de acesso por aplicativo.

Recomendamos a autenticação OAuth2 como a forma mais segura e granular de acessar a REST API do WordPress.com. Se você já está familiarizado com OAuth2, pode ir diretamente para a documentação técnica.

O OAuth2 permite que seu aplicativo atue em nome de um usuário sem nunca ver a senha dele. Veja como funciona: quando alguém quer usar seu app com a conta do WordPress.com, seu app o direciona ao WordPress.com para fazer login. O WordPress.com mostra exatamente o que seu app deseja fazer (como ler posts ou criar novos) e pergunta se está tudo bem. Se a pessoa concordar, o WordPress.com fornece ao seu app um token de acesso especial. Esse token funciona como uma chave temporária que permite ao seu app fazer apenas o que o usuário autorizou.

Você pode pensar nisso como uma conversa entre três partes:

• Usuário: “Gostaria de criar um post por meio deste cliente de API.”
• Cliente (App): “Certo. Ei, WordPress.com, gostaria de fazer algo em nome deste usuário. Você pode perguntar se ele autoriza?”
• WordPress.com: “Claro. Ei, usuário, tudo bem se o Cliente agir em seu nome?”
• Usuário: “Sim, tudo bem. Eu confio neste cliente para realizar ações por mim no futuro.”
• WordPress.com: “Certo, Cliente, aqui está um token que permitirá que você realize ações em nome deste usuário. Mantenha-o em segredo. Mantenha-o seguro.”

Depois que o Cliente (App) obtém o token, ele pode fazer requisições autenticadas ao WordPress.com. Veja como funciona uma interação típica:

• Cliente (App): “Olá, WordPress.com, gostaria de criar um novo post. Aqui está meu token de acesso comprovando que estou autorizado a agir em nome do usuário, junto com o título do post, conteúdo e outros detalhes.”
• WordPress.com: “Validei seu token e confirmei que você tem permissão para criar posts. O post foi criado e publicado com sucesso. Aqui está a resposta com o ID do novo post, a URL e outros metadados.”

Esse fluxo de autenticação baseado em tokens OAuth2 oferece controle de acesso seguro e granular — o Cliente só pode realizar ações que o usuário autorizou explicitamente durante o fluxo OAuth. O token pode ser revogado a qualquer momento, se necessário, e o WordPress.com valida as permissões do token em cada requisição.

A grande vantagem desse sistema é que os usuários mantêm o controle. Eles podem ver exatamente o que seu app está solicitando e podem revogar o acesso a qualquer momento. Seu app nunca armazena senhas e, se um token for comprometido, isso afeta apenas o acesso daquele app específico — não a conta inteira do usuário.

Você provavelmente já viu isso antes ao fazer login em sites usando sua conta do Google ou do Facebook. O processo funciona da mesma forma: você clica em “Fazer login com o Facebook”, é direcionado ao Facebook para confirmar e, em seguida, é redirecionado de volta ao site original.

Da perspectiva do seu app, o processo envolve algumas etapas:

• Primeiro, você registra seu aplicativo no WordPress.com para obter um client ID.
• Em seguida, você direciona os usuários ao WordPress.com com um link especial que inclui seu client ID e informa ao WordPress.com para onde enviar o usuário de volta.
• Quando os usuários autorizam seu app, o WordPress.com os redireciona de volta ao seu app com um código de autorização. Você troca esse código por um token de acesso usando seu client secret e, então, pode usar esse token para fazer requisições à API em nome do usuário.

Depois de ter um token de acesso, fazer requisições autenticadas é simples. Você inclui o token no cabeçalho Authorization das suas requisições desta forma: Authorization: Bearer your_token_here.

Para detalhes completos de implementação, exemplos de código e práticas recomendadas de segurança, confira o guia de autenticação OAuth2.

Estrutura da URL Base

A REST API do WordPress.com oferece uma estrutura de URL base padronizada que garante acesso consistente em todos os tipos de sites, configurações de hospedagem e namespaces da API. Todos os endpoints disponíveis são organizados e agrupados sob diferentes namespaces (como wp, rest e wpcom) e suas respectivas versões (como v1, v1.4, v2, v4), proporcionando separação lógica entre diferentes funcionalidades da API e permitindo estratégias de versionamento independentes. Essa abordagem unificada simplifica a integração com a API e elimina a necessidade de determinar diferentes formatos de URL com base nas características do site ou nas versões da API.

Para informações detalhadas sobre os namespaces disponíveis, suas versões e quais endpoints cada namespace oferece, consulte a documentação de Namespaces e Versões.

Estrutura Geral da URL

Todos os endpoints da REST API do WordPress.com seguem este padrão padronizado:

https://public-api.wordpress.com/{namespace}/{version}/{endpoint}

Placeholders:

• {namespace}: O namespace da API (por exemplo, ‘rest’, ‘wp’, ‘wpcom’)
• {version}: A versão da API (por exemplo, ‘v1’, ‘v1.4’, ‘v2’, ‘v4’)
• {endpoint}: O endpoint específico da API que você deseja acessar

Exemplos:

https://public-api.wordpress.com/rest/v1.4/me
https://public-api.wordpress.com/wpcom/v4/notifications
https://public-api.wordpress.com/wp/v2/posts

Estrutura de URL específica do site

Ao acessar endpoints que operam em sites WordPress.com específicos, a estrutura da URL inclui um identificador de site:

https://public-api.wordpress.com/{namespace}/{version}/sites/{site_id}/{endpoint}

Parâmetros:

• {namespace}: O namespace da API (por exemplo, ‘rest’, ‘wp’, ‘wpcom’)
• {version}: A versão da API (por exemplo, ‘v1’, ‘v1.4’, ‘v2’, ‘v4’)
• {site_id}: O identificador numérico exclusivo do seu site WordPress.com
• {endpoint}: O endpoint específico relacionado ao site (por exemplo, ‘posts’, ‘pages’, ‘media’, ‘users’)

Exemplos:

https://public-api.wordpress.com/wp/v2/sites/241031857/posts
https://public-api.wordpress.com/rest/v1.4/sites/241031857/stats
https://public-api.wordpress.com/wpcom/v2/sites/241031857/follows

Obtendo o ID do seu site

Para usar endpoints específicos de site, você precisará obter o identificador numérico único do seu site. Você pode obter essa informação fazendo uma requisição ao endpoint /rest/v1.1/me/sites a partir do Console da API:

1. Acesse o Console da API do WordPress.com
2. Navegue até o endpoint /rest/v1.1/me/sites (que pode ser encontrado em WP.COM API - v1.1/me/sites no Console)
3. Execute a requisição para recuperar todos os sites associados à sua conta
4. Localize o campo ID na resposta para o site desejado

O endpoint /rest/v1.1/me/sites retorna detalhes completos sobre todos os sites associados à sua conta WordPress.com, incluindo:

• ID: O identificador numérico único do site (o que você precisa para chamadas à API)
• name: O nome de exibição do site
• URL: A URL pública do site
• jetpack: Se o site é um site conectado ao Jetpack
• is_private: Se o site é privado
• capabilities: Quais ações você pode realizar no site

Exemplo de resposta:

{
  "sites": [
    {
      "ID": 241031857,
      "name": "My Blog",
      "URL": "https://myblog.wordpress.com",
      "jetpack": false,
      "is_private": false,
      "capabilities": {
        "edit_posts": true,
        "publish_posts": true
      }
    }
  ]
}

Formatos alternativos de URL

Você pode encontrar alguns formatos alternativos de URL:

• Acesso direto ao site, como https://yoursite.com/wp-json/wp/v2/posts – Este formato funciona apenas para sites auto-hospedados com Jetpack. Pode falhar devido a configurações de segurança, regras de firewall ou problemas de autenticação.
• Acesso ao WordPress.com baseado em domínio, como https://public-api.wordpress.com/wp/v2/sites/yoursite.com/posts – Este formato não é confiável para sites com domínios personalizados, configurações de DNS ou quando os domínios mudam.

Para evitar qualquer problema, a abordagem recomendada é usar o formato com IDs numéricos de site, que é mais confiável, mais rápido, funciona de forma consistente em todos os tipos de site e oferece suporte completo aos recursos e métodos de autenticação do WordPress.com.

Requisitos de autenticação

A REST API do WordPress.com oferece suporte a requisições autenticadas e não autenticadas, dependendo do endpoint e dos dados que você está tentando acessar. Entender quando e como autenticar é fundamental para uma integração bem-sucedida com a API.

Requisições não autenticadas funcionam para:

• Informações públicas do site (por exemplo, detalhes do site, posts públicos)
• Leitura de conteúdo público de sites WordPress.com
• Acesso a estatísticas e dados disponíveis publicamente

Exemplos de requisições não autenticadas:

# Get public information about a site
curl https://public-api.wordpress.com/rest/v1.1/sites/en.blog.wordpress.com/

# Get public posts from a site
curl https://public-api.wordpress.com/wp/v2/sites/en.blog.wordpress.com/posts?per_page=5

A autenticação é necessária para:

• Criar, editar ou excluir conteúdo (posts, páginas, comentários)
• Acessar sites privados ou conteúdo privado
• Gerenciar configurações do site
• Acessar dados específicos do usuário (notificações, sites seguidos, estatísticas pessoais)
• Qualquer operação que exigiria que o usuário tivesse efetuado login ao usar o WordPress.com diretamente

Exemplos de requisições autenticadas (requerem um token):

# Get your user profile (requires authentication)
curl -H "Authorization: Bearer YOUR_ACCESS_TOKEN" 
     https://public-api.wordpress.com/rest/v1.4/me

# Create a new post (requires authentication)
curl -X POST 
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN" 
     -H "Content-Type: application/json" 
     -d '{"title":"My New Post","content":"This is the post content","status":"publish"}' 
     https://public-api.wordpress.com/wp/v2/sites/YOUR_SITE_ID/posts

# Get your site's stats (requires authentication)
curl -H "Authorization: Bearer YOUR_ACCESS_TOKEN" 
     https://public-api.wordpress.com/rest/v1.4/sites/YOUR_SITE_ID/stats

Métodos de Autenticação

Toda autenticação da REST API do WordPress.com é baseada em tokens. Cada requisição autenticada requer um token de acesso OAuth2 obtido a partir dos endpoints OAuth2 do WordPress.com. Os métodos mais relevantes para obter esses tokens são:

• Troca Direta de Token por Credenciais (para uso pessoal e desenvolvimento)
• Fluxo Completo OAuth2 (recomendado para aplicações de terceiros)

Troca Direta de Token por Credenciais

As Senhas de Aplicativo oferecem um atalho para obter tokens de acesso OAuth2 sem implementar o fluxo completo de autorização do usuário. Este método usa o fluxo OAuth2 grant_type=password para trocar diretamente seu nome de usuário do WordPress.com e a Senha de Aplicativo por um token de acesso.

Quando usar este método:

• Projetos pessoais e desenvolvimento
• Ferramentas e scripts de linha de comando
• Aplicações que acessam apenas seus próprios sites WordPress.com
• Testes e prototipagem

Como funciona: Em vez de redirecionar os usuários pela interface de autorização do WordPress.com, você usa sua Senha de Aplicação para solicitar diretamente um token do endpoint OAuth2. Isso ignora a etapa de consentimento do usuário, mas exige suas credenciais reais do WordPress.com.

Como usar a Troca Direta de Token por Credenciais:

Para usar este método, você precisará:

• Criar uma nova aplicação WordPress.com para obter o Client ID e o Client Secret do seu app.
• Se você tiver a autenticação em dois fatores ativada (altamente recomendado), crie uma nova Senha de Aplicação. Caso contrário, use sua senha comum.

Este método usa o fluxo OAuth2 grant_type=password para trocar diretamente sua Senha de Aplicação por um token de acesso:

# Step 1: Generate an OAuth2 access token using your Application Password
curl -X POST "https://public-api.wordpress.com/oauth2/token" 
  -d "client_id=<CLIENT_ID>" 
  -d "client_secret=<CLIENT_SECRET>" 
  -d "grant_type=password" 
  -d "username=<USERNAME>" 
  -d "password=<APPLICATION_PASSWORD>"


# Response will contain your access token:
# {
#   "access_token": "your_oauth2_token_here",
#   "token_type": "bearer",
#   "scope": "global"
# }

# Step 2: Use the OAuth2 token for all API requests
curl -X GET 
  'https://public-api.wordpress.com/rest/v1.1/sites/YOUR_SITE_ID/posts' 
  -H 'Authorization: Bearer your_oauth2_token_here' 
  -H 'Content-Type: application/json'

# Create a post using the token
curl -X POST 
  'https://public-api.wordpress.com/wp/v2/sites/YOUR_SITE_ID/posts' 
  -H 'Authorization: Bearer your_oauth2_token_here' 
  -H 'Content-Type: application/json' 
  -d '{"title":"My New Post","content":"Post content here","status":"publish"}'

Pontos importantes:

• As Senhas de Aplicação nunca são usadas diretamente com os endpoints do public-api.wordpress.com
• Elas são usadas apenas com o endpoint de token OAuth2 para obter tokens de acesso
• O token resultante é idêntico aos tokens obtidos pelo fluxo OAuth2 completo
• Todas as requisições subsequentes à API usam o token OAuth2, não a Senha de Aplicação

Fluxo OAuth2 Completo

O fluxo completo do OAuth2 é a abordagem recomendada para aplicações de terceiros que precisam que os usuários autorizem o acesso aos seus sites e dados do WordPress.com. Este método oferece o sistema de permissões mais seguro e granular.

Quando usar este método:

• Aplicações de terceiros acessando dados de usuários
• Aplicações web com múltiplos usuários
• Apps
• Qualquer app que precise de permissões controladas pelo usuário

Como funciona: Os usuários são redirecionados para o WordPress.com, onde podem revisar e autorizar as permissões específicas que sua aplicação está solicitando. Após a autorização, sua aplicação recebe um token de acesso que pode ser usado para fazer requisições à API em nome do usuário.

Resumo do fluxo completo do OAuth2:

1. Registre sua aplicação em WordPress.com Apps para obter seu client ID e secret
2. Redirecione os usuários para a URL de autorização do WordPress.com com seu client ID e escopos solicitados
3. O usuário revisa e concede permissão através da interface do WordPress.com
4. O WordPress.com redireciona de volta para seu app com um código de autorização
5. Troque o código de autorização por um token de acesso OAuth2 usando seu client secret
6. Use o token de acesso OAuth2 em todas as requisições à API com Authorization: Bearer YOUR_TOKEN

O resultado é o mesmo formato de token de acesso OAuth2 usado pelo método Credentials Direct Token Exchange, garantindo autenticação consistente em ambas as abordagens.

Para orientações detalhadas sobre a implementação do OAuth2, incluindo exemplos de código e considerações de segurança, consulte a documentação de OAuth2 Authentication.

Solução de problemas e boas práticas de autenticação

Erros comuns de autenticação

401 Unauthorized

• Causa: Token de acesso inválido ou ausente
• Solução: Verifique se o seu token está correto e incluído no cabeçalho Authorization

403 Forbidden

• Causa: Token válido, mas permissões insuficientes para a ação solicitada
• Solução: Verifique se a sua conta de usuário possui as capacidades necessárias para o site

Formato de Token Inválido

• Causa: Formato de cabeçalho incorreto
• Solução: Certifique-se de que está usando Authorization: Bearer YOUR_TOKEN (observe o espaço após “Bearer”)

Melhores Práticas de Segurança

1. Nunca exponha credenciais em código do lado do cliente – Senhas de aplicativo devem ser usadas apenas em aplicações do lado do servidor
2. Use variáveis de ambiente – Armazene nomes de usuário e senhas em variáveis de ambiente, não no seu código-fonte
3. Faça a rotação de senhas regularmente – Gere novas senhas de aplicativo periodicamente e revogue as antigas
4. Use OAuth2 para aplicações voltadas ao usuário – Não use senhas de aplicativo para aplicações com as quais outros usuários irão se autenticar
5. Entenda o sistema unificado de tokens – Ambos os métodos de autenticação resultam nos mesmos tokens de acesso OAuth2, proporcionando acesso e segurança consistentes à API
6. Escolha o método certo – Use o atalho de Senha de Aplicativo para uso pessoal/desenvolvimento, e o fluxo completo de OAuth2 para aplicações de terceiros
7. Gerenciamento de tokens – Os tokens podem ser revogados por aplicação sem afetar outros apps, proporcionando melhor segurança do que compartilhar senhas

Aplicações Baseadas em Navegador

Se você está desenvolvendo uma aplicação baseada em navegador, será necessário:

1. Use o fluxo implícito do OAuth2 – Senhas de aplicativo não devem ser usadas em código do lado do cliente
2. Adicione seus domínios à lista de permissões – Configure as origens permitidas nas configurações do app WordPress.com
3. Lide com CORS corretamente – A API enviará os cabeçalhos CORS apropriados para domínios na lista de permissões

Para orientações detalhadas sobre implementações baseadas em navegador, consulte Usando a REST API a partir de JS e do navegador.

Recursos e documentação

• Console da API – Testes interativos e exploração
• Referência da API – Documentação abrangente dos endpoints
• WordPress REST API Handbook – Documentação oficial da REST API do WordPress core
• Blog de Desenvolvimento – Atualizações e anúncios sobre mudanças na API