Espaces de noms et versions

L’API REST WordPress.com est organisée en trois espaces de noms distincts, chacun servant des objectifs spécifiques et suivant des schémas de versionnement indépendants. Comprendre ces espaces de noms est essentiel pour choisir les bons points de terminaison pour votre intégration et garantir la compatibilité avec WordPress.com et les sites WordPress auto-hébergés.

Vue d’ensemble des espaces de noms de l’API

L’API REST WordPress.com fournit trois espaces de noms principaux, chacun ciblant différents cas d’utilisation et niveaux de compatibilité :

Espace de noms	Versions disponibles	Objectif principal	Compatible avec le cœur de WordPress
/rest/	v1, v1.1, v1.2, v1.3, v1.4	Gestion historique de WordPress.com et fonctionnalités de la plateforme	Non
/wp/	v2	Ressources standard du cœur de WordPress suivant la spécification officielle de l’API REST	Oui
/wpcom/	v2, v3, v4	Fonctionnalités et services modernes spécifiques à WordPress.com	Non

Espace de noms /rest/ – API historique de WordPress.com

L’espace de noms /rest/ représente l’API REST originale de WordPress.com, antérieure à l’API REST du cœur de WordPress. Il fournit un accès complet aux fonctionnalités de la plateforme WordPress.com et aux capacités de gestion des sites.

Versions disponibles : v1, v1.1, v1.2, v1.3, v1.4 (accessibles via l’option WP.COM API dans la console de l’API)

URL de 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/

Fonctionnalités clés :

• Gestion complète des sites et des utilisateurs
• Fonctionnalités spécifiques à WordPress.com comme les statistiques, le Lecteur et les Notifications
• Configuration avancée des sites et gestion des domaines
• Capacités d’intégration avec Jetpack

Stratégie de versionnement : Chaque version (v1.1–v1.4) a introduit des améliorations progressives, de nouveaux points de terminaison et des fonctionnalités enrichies tout en maintenant la rétrocompatibilité. Lorsque des points de terminaison existent dans plusieurs versions, les versions plus récentes offrent généralement des champs supplémentaires, de meilleures performances ou des corrections de bugs.

Idéal pour :

• Accéder aux fonctionnalités spécifiques à WordPress.com non disponibles ailleurs
• Gestion et configuration avancées des sites
• Maintenir la compatibilité avec les intégrations existantes
• Fonctionnalités telles que les statistiques détaillées, les fonctionnalités du Lecteur et la gestion des domaines

Exemples de points de terminaison :

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

Espace de noms /wp/ – API REST du cœur de WordPress

L’espace de noms /wp/ implémente la spécification officielle de l’API REST de WordPress, garantissant une compatibilité totale avec les sites WordPress.com et les sites WordPress auto-hébergés. Cet espace de noms suit les standards établis par l’équipe du cœur de WordPress.

Version disponible : v2 (accessible via l’option WP REST API dans la console API)

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

Fonctionnalités clés :

• Ressources WordPress standard (articles, pages, commentaires, taxonomies, utilisateurs, médias)
• Compatibilité totale avec les sites WordPress auto-hébergés
• Structure des points de terminaison cohérente suivant les standards du cœur de WordPress
• Extensible via des extensions sur les sites auto-hébergés

Philosophie de conception : Cet espace de noms privilégie la standardisation et la compatibilité par rapport aux fonctionnalités spécifiques à WordPress.com. Il reproduit la REST API disponible sur toute installation WordPress, ce qui le rend idéal pour les applications devant fonctionner dans différents environnements WordPress.

Idéal pour :

• Les nouveaux projets nécessitant les fonctionnalités du cœur de WordPress
• Les applications devant fonctionner à la fois avec WordPress.com et les sites auto-hébergés
• La gestion de contenu standard (articles, pages, médias, utilisateurs)
• Les intégrations avec les outils et extensions WordPress existants

Exemples de points de terminaison :

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

Espace de noms /wpcom/ – API moderne de la plateforme WordPress.com

L’espace de noms /wpcom/ représente l’évolution des fonctionnalités d’API spécifiques à WordPress.com, avec des modèles de conception modernes et des fonctionnalités avancées de la plateforme non disponibles dans le cœur de WordPress.

Versions disponibles : v2, v3, v4 (accessibles via l’option WP REST API dans la console API)

URL de base :

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

Fonctionnalités clés :

• Conception d’API moderne avec une structure et des performances améliorées
• Services avancés de WordPress.com (Lecteur, statistiques améliorées, Notifications)
• Fonctionnalités d’engagement des utilisateurs (abonnements, mentions J’aime, recommandations)
• Fonctionnalités spécifiques à la plateforme non disponibles dans WordPress auto-hébergé

Stratégie de versionnement : Chaque version introduit de nouvelles capacités, des améliorations de sécurité et des structures de données affinées. Contrairement à l’espace de noms /rest/, /wpcom/ se concentre sur les fonctionnalités tournées vers l’avenir plutôt que sur la compatibilité avec les versions antérieures.

Idéal pour :

• Les fonctionnalités modernes de la plateforme WordPress.com
• Les fonctionnalités d’engagement des utilisateurs et les fonctionnalités sociales
• Les analyses avancées et les recommandations
• Les nouvelles intégrations nécessitant les dernières capacités de WordPress.com

Exemples de points de terminaison :

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

Choisir le bon espace de noms

Le choix de l’espace de noms dépend de vos besoins spécifiques et de vos exigences en matière de compatibilité :

Utilisez /wp/v2/ lorsque vous avez besoin des fonctionnalités standard de WordPress comme :

• Les fonctionnalités principales de WordPress (articles, pages, utilisateurs, médias)
• La compatibilité avec les sites WordPress auto-hébergés
• Les modèles et structures standard de la REST API
• L’intégration avec les outils et extensions WordPress existants

Utilisez /wpcom/v4/ (ou la dernière version disponible) lorsque vous avez besoin des fonctionnalités de la plateforme WordPress.com comme :

• Les services avancés et les fonctionnalités sociales de WordPress.com
• Une conception d’API moderne et des performances améliorées
• Les dernières capacités et intégrations de la plateforme
• Les fonctionnalités propres à l’écosystème WordPress.com

Utilisez /rest/v1.4/ (ou la version requise) lorsque vous avez besoin de fonctionnalités héritées et de compatibilité comme :

• Des fonctionnalités spécifiques disponibles uniquement via les points de terminaison hérités
• La rétrocompatibilité avec les intégrations existantes
• Des fonctionnalités avancées de gestion de site qui n’ont pas encore été migrées vers les espaces de noms plus récents
• Des capacités complètes de statistiques et d’analyse

Recommandations pour le choix de la version

Au sein de chaque espace de noms, la sélection de version suit ces principes :

Plusieurs versions disponibles : Lorsque des points de terminaison existent dans plusieurs versions, les versions plus récentes offrent généralement :

• Des champs de réponse et des paramètres supplémentaires
• Des performances et une fiabilité améliorées
• Des corrections de bugs et des améliorations de sécurité
• Des fonctionnalités enrichies tout en maintenant la rétrocompatibilité

Approche recommandée : Utilisez toujours la dernière version disponible, sauf si :

• Votre intégration dépend d’un comportement spécifique des versions antérieures
• Vous maintenez du code existant qui nécessite des réponses API spécifiques
• Des exigences de compatibilité imposent une version particulière

Comprendre l’organisation de la console API

La console API WordPress.com organise les espaces de noms en deux catégories principales :

• WP.COM API : contient toutes les versions de l’espace de noms /rest/ (v1–v1.4)
• WP REST API : contient /wp/v2/ et toutes les versions de l’espace de noms /wpcom/ (v2–v4)

Cette organisation reflète l’évolution des API spécifiques à WordPress.com vers les API standardisées du cœur de WordPress et les fonctionnalités modernes de la plateforme.

Considérations relatives à la migration

Lors de la planification d’intégrations ou de la mise à jour d’intégrations existantes :

Nouveaux projets : Commencez par /wp/v2/ pour les fonctionnalités de base et /wpcom/v4/ pour les fonctionnalités spécifiques à la plateforme.

Intégrations existantes : Envisagez de migrer des points de terminaison /rest/ vers des espaces de noms plus récents lorsque :

• Une fonctionnalité équivalente existe dans /wp/v2/ ou /wpcom/
• Vous avez besoin de meilleures performances ou de fonctionnalités supplémentaires
• La maintenance et le support à long terme sont des priorités

Disponibilité des fonctionnalités : Certaines fonctionnalités avancées restent exclusives à l’espace de noms /rest/. Évaluez les exigences fonctionnelles avant la migration pour vous assurer que toutes les fonctionnalités nécessaires sont disponibles dans les espaces de noms cibles.