Namespaces e versões

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

A REST API do WordPress.com é organizada em três namespaces distintos, cada um atendendo a propósitos específicos e seguindo esquemas de versionamento independentes. Entender esses namespaces é essencial para escolher os endpoints certos para sua integração e garantir a compatibilidade tanto com o WordPress.com quanto com sites WordPress auto-hospedados.

Visão geral dos namespaces da API

A REST API do WordPress.com oferece três namespaces principais, cada um voltado para diferentes casos de uso e níveis de compatibilidade:

Namespace	Versões disponíveis	Propósito principal	Compatível com o WordPress Core
/rest/	v1, v1.1, v1.2, v1.3, v1.4	Gerenciamento legado do WordPress.com e recursos da plataforma	Não
/wp/	v2	Recursos padrão do WordPress core seguindo a especificação oficial da REST API	Sim
/wpcom/	v2, v3, v4	Recursos e serviços modernos específicos do WordPress.com	Não

Namespace /rest/ – API legada do WordPress.com

O namespace /rest/ representa a REST API original do WordPress.com, anterior à REST API do WordPress core. Ele oferece acesso abrangente aos recursos da plataforma WordPress.com e às funcionalidades de gerenciamento de sites.

Versões disponíveis: v1, v1.1, v1.2, v1.3, v1.4 (acessadas pela opção WP.COM API no Console da API)

URLs base:

• https://public-api.wordpress.com/rest/v1/
• https://public-api.wordpress.com/rest/v1.1/
• https://public-api.wordpress.com/rest/v1.2/
• https://public-api.wordpress.com/rest/v1.3/
• https://public-api.wordpress.com/rest/v1.4/

Principais Recursos:

• Gerenciamento abrangente de sites e usuários
• Recursos específicos do WordPress.com, como Estatísticas, Leitor e Notificações
• Configuração avançada de sites e gerenciamento de domínios
• Capacidades de integração com o Jetpack

Estratégia de Versionamento: Cada versão (v1.1–v1.4) introduziu melhorias incrementais, novos endpoints e funcionalidades aprimoradas, mantendo a compatibilidade retroativa. Quando os endpoints existem em várias versões, as versões mais recentes geralmente oferecem campos adicionais, desempenho aprimorado ou correções de bugs.

Melhor Utilizado Para:

• Acessar recursos específicos do WordPress.com não disponíveis em outros lugares
• Gerenciamento e configuração avançados de sites
• Manter compatibilidade com integrações existentes
• Recursos como estatísticas detalhadas, funcionalidade do Leitor e gerenciamento de domínios

Exemplos de Endpoints:

• /rest/v1.4/sites/{site}/posts
• /rest/v1.4/sites/{site}/stats
• /rest/v1.4/me/sites
• /rest/v1.3/read/following

Namespace /wp/ – REST API Core do WordPress

O namespace /wp/ implementa a especificação oficial da REST API do WordPress, garantindo total compatibilidade tanto com o WordPress.com quanto com sites WordPress auto-hospedados. Este namespace segue os padrões estabelecidos pela equipe core do WordPress.

Versão Disponível: v2 (acessada pela opção WP REST API no Console de API)

URL Base: https://public-api.wordpress.com/wp/v2/

Principais Recursos:

• Recursos padrão do WordPress (posts, páginas, comentários, taxonomias, usuários, mídia)
• Compatibilidade total com sites WordPress auto-hospedados
• Estrutura de endpoints consistente seguindo os padrões do WordPress core
• Extensível por meio de plugins em sites auto-hospedados

Filosofia de Design: Este namespace prioriza a padronização e a compatibilidade em vez de recursos específicos do WordPress.com. Ele espelha a REST API disponível em qualquer instalação WordPress, sendo ideal para aplicações que precisam funcionar em diferentes ambientes WordPress.

Melhor Utilizado Para:

• Novos projetos que exigem funcionalidades do WordPress core
• Aplicações que precisam funcionar tanto com WordPress.com quanto com sites auto-hospedados
• Gerenciamento de conteúdo padrão (posts, páginas, mídia, usuários)
• Integrações com ferramentas e plugins existentes do WordPress

Exemplos de Endpoints:

• /wp/v2/posts
• /wp/v2/pages
• /wp/v2/users
• /wp/v2/media
• /wp/v2/sites/{site}/posts

Namespace /wpcom/ – API Moderna da Plataforma WordPress.com

O namespace /wpcom/ representa a evolução da funcionalidade de API específica do WordPress.com, apresentando padrões de design moderno e recursos avançados da plataforma que não estão disponíveis no WordPress core.

Versões Disponíveis: v2, v3, v4 (acessadas pela opção WP REST API no Console de API)

URLs Base:

• https://public-api.wordpress.com/wpcom/v2/
• https://public-api.wordpress.com/wpcom/v3/
• https://public-api.wordpress.com/wpcom/v4/

Principais Recursos:

• Design moderno de API com estrutura e desempenho aprimorados
• Serviços avançados do WordPress.com (Leitor, Estatísticas aprimoradas, Notificações)
• Recursos de engajamento do usuário (seguir, curtidas, recomendações)
• Funcionalidades específicas da plataforma que não estão disponíveis no WordPress auto-hospedado

Estratégia de Versionamento: Cada versão introduz novas capacidades, melhorias de segurança e estruturas de dados refinadas. Diferente do namespace /rest/, o /wpcom/ foca em funcionalidades voltadas para o futuro, em vez de compatibilidade com versões anteriores.

Melhor Utilizado Para:

• Recursos modernos da plataforma WordPress.com
• Engajamento do usuário e recursos sociais
• Análises avançadas e recomendações
• Novas integrações que exigem as capacidades mais recentes do WordPress.com

Exemplos de Endpoints:

• /wpcom/v4/me/follows
• /wpcom/v3/notifications
• /wpcom/v2/read/tags
• /wpcom/v4/sites/{site}/stats/insights

Escolhendo o Namespace Certo

A escolha do namespace depende dos seus requisitos específicos e necessidades de compatibilidade:

Use /wp/v2/ quando precisar de Funcionalidades Padrão do WordPress como:

• Recursos principais do WordPress (posts, páginas, usuários, mídia)
• Compatibilidade com sites WordPress auto-hospedados
• Padrões e estruturas da REST API padrão
• Integração com ferramentas e plugins existentes do WordPress

Use /wpcom/v4/ (ou a versão mais recente disponível) quando precisar de Recursos da Plataforma WordPress.com como:

• Serviços avançados do WordPress.com e recursos sociais
• Design moderno de API e desempenho aprimorado
• Capacidades e integrações mais recentes da plataforma
• Recursos exclusivos do ecossistema WordPress.com

Use /rest/v1.4/ (ou a versão necessária) quando precisar de Recursos Legados e Compatibilidade como:

• Funcionalidades específicas disponíveis apenas em endpoints legados
• Compatibilidade retroativa com integrações existentes
• Recursos avançados de gerenciamento de sites que ainda não foram migrados para namespaces mais recentes
• Capacidades abrangentes de estatísticas e análises

Diretrizes para Seleção de Versão

Dentro de cada namespace, a seleção de versão segue estes princípios:

Múltiplas versões disponíveis: Quando endpoints existem em múltiplas versões, as versões mais recentes geralmente oferecem:

• Campos de resposta e parâmetros adicionais
• Melhor desempenho e confiabilidade
• Correções de bugs e melhorias de segurança
• Funcionalidades aprimoradas mantendo a compatibilidade com versões anteriores

Abordagem recomendada: Sempre use a versão mais recente disponível, a menos que:

• Sua integração dependa de um comportamento específico de versões anteriores
• Você esteja mantendo código legado que exige respostas específicas da API
• Requisitos de compatibilidade determinem uma versão específica

Entendendo a organização do Console da API

O Console da API do WordPress.com organiza os namespaces em duas categorias principais:

• WP.COM API: Contém todas as versões do namespace /rest/ (v1–v1.4)
• WP REST API: Contém /wp/v2/ e todas as versões do namespace /wpcom/ (v2–v4)

Essa organização reflete a evolução das APIs específicas do WordPress.com para APIs padronizadas do core do WordPress e recursos modernos da plataforma.

Considerações sobre migração

Ao planejar integrações ou atualizar as existentes:

Novos projetos: Comece com /wp/v2/ para funcionalidades principais e /wpcom/v4/ para recursos específicos da plataforma.

Integrações existentes: Considere migrar dos endpoints /rest/ para namespaces mais recentes quando:

• Funcionalidade equivalente existir em /wp/v2/ ou /wpcom/
• Você precisar de melhor desempenho ou recursos adicionais
• Manutenção e suporte a longo prazo forem prioridades

Disponibilidade de recursos: Alguns recursos avançados permanecem exclusivos do namespace /rest/. Avalie os requisitos de funcionalidade antes da migração para garantir que todas as funcionalidades necessárias estejam disponíveis nos namespaces de destino.