Espacios de nombres y versiones

La REST API de WordPress.com está organizada en tres espacios de nombres distintos, cada uno con propósitos específicos y siguiendo esquemas de versionado independientes. Comprender estos espacios de nombres es esencial para elegir los endpoints adecuados para tu integración y garantizar la compatibilidad tanto con WordPress.com como con sitios autoalojados de WordPress.

Resumen de los espacios de nombres de la API

La REST API de WordPress.com proporciona tres espacios de nombres principales, cada uno orientado a casos de uso y niveles de compatibilidad diferentes:

Espacio de nombres	Versiones disponibles	Propósito principal	Compatible con el núcleo de WordPress
/rest/	v1, v1.1, v1.2, v1.3, v1.4	Gestión heredada de WordPress.com y funciones de la plataforma	No
/wp/	v2	Recursos estándar del núcleo de WordPress que siguen la especificación oficial de la REST API	Sí
/wpcom/	v2, v3, v4	Funciones y servicios modernos específicos de WordPress.com	No

Espacio de nombres /rest/ – API heredada de WordPress.com

El espacio de nombres /rest/ representa la REST API original de WordPress.com, anterior a la REST API del núcleo de WordPress. Ofrece acceso completo a las funciones de la plataforma WordPress.com y a las capacidades de gestión del sitio.

Versiones disponibles: v1, v1.1, v1.2, v1.3, v1.4 (accesibles a través de la opción WP.COM API en la consola de la 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/

Características principales:

• Gestión completa de sitios y usuarios
• Funciones específicas de WordPress.com como Estadísticas, Lector y Notificaciones
• Configuración avanzada del sitio y gestión de dominios
• Capacidades de integración con Jetpack

Estrategia de versionado: Cada versión (v1.1–v1.4) introdujo mejoras incrementales, nuevos endpoints y funcionalidad ampliada manteniendo la compatibilidad con versiones anteriores. Cuando los endpoints existen en varias versiones, las versiones más nuevas suelen ofrecer campos adicionales, mejor rendimiento o correcciones de errores.

Mejor uso para:

• Acceder a funciones específicas de WordPress.com no disponibles en otros lugares
• Gestión y configuración avanzadas del sitio
• Mantener la compatibilidad con integraciones existentes
• Funciones como estadísticas detalladas, funcionalidad del Lector y gestión de dominios

Endpoints de ejemplo:

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

Espacio de nombres /wp/ – REST API del núcleo de WordPress

El espacio de nombres /wp/ implementa la especificación oficial de la REST API de WordPress, garantizando una compatibilidad total tanto con WordPress.com como con sitios autoalojados de WordPress. Este espacio de nombres sigue los estándares establecidos por el equipo del núcleo de WordPress.

Versión disponible: v2 (accesible a través de la opción WP REST API en la consola de la API)

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

Características principales:

• Recursos estándar de WordPress (entradas, páginas, comentarios, taxonomías, usuarios, medios)
• Compatibilidad total con sitios autoalojados de WordPress
• Estructura de endpoints coherente que sigue los estándares del núcleo de WordPress
• Ampliable mediante plugins en sitios autoalojados

Filosofía de diseño: Este espacio de nombres prioriza la estandarización y la compatibilidad sobre las funciones específicas de WordPress.com. Refleja la REST API disponible en cualquier instalación de WordPress, lo que la hace ideal para aplicaciones que necesitan funcionar en distintos entornos de WordPress.

Mejor uso para:

• Nuevos proyectos que requieran la funcionalidad del núcleo de WordPress
• Aplicaciones que deban funcionar tanto con WordPress.com como con sitios autoalojados
• Gestión estándar de contenido (entradas, páginas, medios, usuarios)
• Integraciones con herramientas y plugins de WordPress existentes

Endpoints de ejemplo:

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

Espacio de nombres /wpcom/ – API moderna de la plataforma WordPress.com

El espacio de nombres /wpcom/ representa la evolución de la funcionalidad específica de la API de WordPress.com, con patrones de diseño modernos y funciones avanzadas de la plataforma no disponibles en el núcleo de WordPress.

Versiones disponibles: v2, v3, v4 (accesibles a través de la opción WP REST API en la consola de la API)

URLs base:

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

Características principales:

• Diseño de API moderno con estructura y rendimiento mejorados
• Servicios avanzados de WordPress.com (Lector, estadísticas mejoradas, Notificaciones)
• Funciones de interacción con el usuario (seguir, me gusta, recomendaciones)
• Funcionalidad específica de la plataforma no disponible en WordPress autoalojado

Estrategia de versionado: Cada versión introduce nuevas capacidades, mejoras de seguridad y estructuras de datos refinadas. A diferencia del espacio de nombres /rest/, /wpcom/ se centra en la funcionalidad orientada al futuro en lugar de la compatibilidad heredada.

Mejor uso para:

• Funciones modernas de la plataforma WordPress.com
• Funciones sociales y de interacción con el usuario
• Análisis y recomendaciones avanzados
• Nuevas integraciones que requieran las últimas capacidades de WordPress.com

Endpoints de ejemplo:

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

Elegir el espacio de nombres adecuado

La elección del espacio de nombres depende de tus requisitos específicos y de tus necesidades de compatibilidad:

Usa /wp/v2/ cuando necesites funcionalidad estándar de WordPress como:

• Funciones del núcleo de WordPress (entradas, páginas, usuarios, medios)
• Compatibilidad con sitios autoalojados de WordPress
• Patrones y estructuras estándar de la REST API
• Integración con herramientas y plugins de WordPress existentes

Usa /wpcom/v4/ (o la última disponible) cuando necesites funciones de la plataforma WordPress.com como:

• Servicios avanzados de WordPress.com y funciones sociales
• Diseño de API moderno y rendimiento mejorado
• Las últimas capacidades de la plataforma e integraciones
• Funciones exclusivas del ecosistema de WordPress.com

Usa /rest/v1.4/ (o la versión necesaria) cuando necesites funciones heredadas y compatibilidad como:

• Funcionalidad específica disponible solo en endpoints heredados
• Compatibilidad con versiones anteriores para integraciones existentes
• Funciones avanzadas de gestión del sitio que aún no se han migrado a espacios de nombres más nuevos
• Capacidades completas de estadísticas y analítica

Pautas para elegir la versión

Dentro de cada espacio de nombres, la selección de versión sigue estos principios:

Varias versiones disponibles: Cuando los endpoints existen en varias versiones, las versiones más nuevas suelen ofrecer:

• Campos y parámetros de respuesta adicionales
• Mejor rendimiento y fiabilidad
• Correcciones de errores y mejoras de seguridad
• Funcionalidad mejorada manteniendo la compatibilidad con versiones anteriores

Enfoque recomendado: Usa siempre la última versión disponible salvo que:

• Tu integración dependa de un comportamiento específico de versiones anteriores
• Estés manteniendo código heredado que requiera respuestas concretas de la API
• Los requisitos de compatibilidad obliguen a usar una versión concreta

Cómo se organiza la consola de la API

La consola de la API de WordPress.com organiza los espacios de nombres en dos categorías principales:

• WP.COM API: Contiene todas las versiones del espacio de nombres /rest/ (v1–v1.4)
• WP REST API: Contiene /wp/v2/ y todas las versiones del espacio de nombres /wpcom/ (v2–v4)

Esta organización refleja la evolución desde APIs específicas de WordPress.com hacia APIs estandarizadas del núcleo de WordPress y funciones modernas de la plataforma.

Consideraciones para la migración

Al planificar integraciones o actualizar las existentes:

Nuevos proyectos: Empieza con /wp/v2/ para la funcionalidad básica y /wpcom/v4/ para las funciones específicas de la plataforma.

Integraciones existentes: Considera migrar desde los endpoints /rest/ a espacios de nombres más nuevos cuando:

• Exista funcionalidad equivalente en /wp/v2/ o /wpcom/
• Necesites mejor rendimiento o funciones adicionales
• El mantenimiento y soporte a largo plazo sean prioritarios

Disponibilidad de funciones: Algunas funciones avanzadas siguen siendo exclusivas del espacio de nombres /rest/. Evalúa los requisitos de funciones antes de la migración para asegurarte de que toda la funcionalidad necesaria esté disponible en los espacios de nombres de destino.