Premiers pas avec le REST API

Ce texte a été traduit à l’aide de l’IA. Si vous souhaitez consulter le texte original en anglais, cliquez ici.

L’API REST WordPress.com vous permet de consulter, créer ou modifier du contenu sur n’importe quel site WordPress.com, ainsi que sur tout site auto-hébergé (WordPress.org) connecté via Jetpack. Cela inclut non seulement les articles de blog et les pages, mais aussi les commentaires, les étiquettes, les catégories, les médias, les statistiques du site, les notifications, les options de partage, les profils utilisateurs et de nombreuses autres fonctionnalités de WordPress.com.

Certaines requêtes (par exemple, lister les publications publiques) n’ont pas besoin d’être authentifiées, mais toute action qui nécessiterait qu’un utilisateur soit connecté (comme la création d’un article) requiert un jeton d’authentification.

Pour effectuer des requêtes authentifiées, vous devrez d’abord créer un compte sur WordPress.com si vous n’en avez pas déjà un.

Comment l’utiliser

Il existe deux façons d’explorer les points de terminaison disponibles pour l’API REST WordPress.com :

• La page de documentation de référence de l’API REST liste les points de terminaison disponibles et détaille les entrées et sorties de chacun, avec des exemples de code en curl et PHP.
• La console de développement de l’API REST vous permet de construire et d’essayer de véritables requêtes API.

Effectuer des requêtes non authentifiées est simple. Puisqu’aucun en-tête spécial n’est requis, vous pouvez même ouvrir celle-ci dans votre navigateur pour voir ce qu’elle retournera : https://public-api.wordpress.com/rest/v1.1/sites/en.blog.wordpress.com/posts/?number=2&pretty=true

Effectuer des requêtes authentifiées nécessite quelques étapes supplémentaires. Toutes les requêtes authentifiées vers l’API REST WordPress.com nécessitent un jeton d’accès OAuth2. Ce jeton doit être obtenu auprès des points de terminaison OAuth2 de WordPress.com et peut être acquis via différents flux, les plus pertinents étant :

1. Flux OAuth2 complet – Les utilisateurs autorisent votre application via l’interface de WordPress.com, en accordant des permissions spécifiques. C’est l’approche la plus sécurisée et elle est requise pour les applications tierces.
2. Échange direct de jeton par identifiants – Utilisez un mot de passe d’application avec grant_type=password pour obtenir directement un jeton pour vos propres sites. Cela contourne l’étape d’autorisation utilisateur mais nécessite vos identifiants WordPress.com.

Les deux méthodes produisent le même type de jeton d’accès OAuth2 que vous incluez dans les requêtes sous la forme Authorization: Bearer YOUR_ACCESS_TOKEN. L’approche par jeton garantit une sécurité cohérente et permet un contrôle d’accès par application.

Nous recommandons l’authentification OAuth2 comme le moyen le plus sécurisé et le plus granulaire d’accéder à la REST API de WordPress.com. Si vous êtes déjà familier avec OAuth2, vous pouvez passer directement à la documentation technique.

OAuth2 permet à votre application d’agir au nom d’un utilisateur sans jamais voir son mot de passe. Voici comment cela fonctionne : lorsqu’une personne souhaite utiliser votre application avec son compte WordPress.com, votre application l’envoie sur WordPress.com pour se connecter. WordPress.com lui montre exactement ce que votre application souhaite faire (comme lire ses articles ou en créer de nouveaux) et demande si c’est acceptable. Si la personne accepte, WordPress.com fournit à votre application un jeton d’accès spécial. Ce jeton est comme une clé temporaire qui permet à votre application de faire uniquement ce que l’utilisateur a accepté.

Vous pouvez voir cela comme une conversation à trois :

• Utilisateur : « J’aimerais publier un article via ce client API. »
• Client (Application) : « D’accord. Hé, WordPress.com, j’aimerais faire quelque chose au nom de cet utilisateur. Pouvez-vous lui demander si c’est acceptable ? »
• WordPress.com : « Bien sûr. Hé, utilisateur, est-ce que c’est acceptable si le Client agit en votre nom ? »
• Utilisateur : « Oui, c’est acceptable. Je fais confiance à ce client pour effectuer des actions en mon nom à l’avenir. »
• WordPress.com : « D’accord, Client, voici un jeton qui vous permettra d’effectuer des actions pour cet utilisateur. Gardez-le secret. Gardez-le en sécurité. »

Une fois que le Client (Application) a obtenu le jeton, il peut effectuer des requêtes authentifiées auprès de WordPress.com. Voici comment fonctionne une interaction typique :

• Client (Application) : « Bonjour WordPress.com, j’aimerais créer un nouvel article. Voici mon jeton d’accès prouvant que je suis autorisé à agir au nom de l’utilisateur, ainsi que le titre de l’article, le contenu et d’autres détails. »
• WordPress.com : « J’ai validé votre jeton et confirmé que vous avez la permission de créer des articles. L’article a été créé et publié avec succès. Voici la réponse avec l’ID du nouvel article, l’URL et d’autres métadonnées. »

Ce flux d’authentification par jeton OAuth2 fournit un contrôle d’accès sécurisé et granulaire — le Client ne peut effectuer que les actions que l’utilisateur a explicitement autorisées lors du flux OAuth. Le jeton peut être révoqué à tout moment si nécessaire, et WordPress.com valide les permissions du jeton à chaque requête.

L’avantage de ce système est que les utilisateurs gardent le contrôle. Ils peuvent voir exactement ce que votre application demande, et ils peuvent révoquer l’accès à tout moment. Votre application ne stocke jamais de mots de passe, et si un jeton est compromis, cela n’affecte que l’accès de cette seule application — pas l’ensemble du compte de l’utilisateur.

Vous avez probablement déjà vu cela en vous connectant à des sites web avec votre compte Google ou Facebook. Le processus fonctionne de la même manière : vous cliquez sur « Se connecter avec Facebook », vous êtes redirigé vers Facebook pour confirmer, puis vous êtes redirigé vers le site d’origine.

Du point de vue de votre application, le processus implique plusieurs étapes :

• Tout d’abord, vous enregistrez votre application sur WordPress.com pour obtenir un client ID.
• Ensuite, vous dirigez les utilisateurs vers WordPress.com avec un lien spécial qui inclut votre client ID et indique à WordPress.com où renvoyer l’utilisateur.
• Lorsque les utilisateurs autorisent votre application, WordPress.com les redirige vers votre application avec un code d’autorisation. Vous échangez ce code contre un jeton d’accès en utilisant votre client secret, puis vous pouvez utiliser ce jeton pour effectuer des requêtes API au nom de l’utilisateur.

Une fois que vous disposez d’un jeton d’accès, effectuer des requêtes authentifiées est simple. Vous incluez le jeton dans l’en-tête Authorization de vos requêtes comme ceci : Authorization: Bearer your_token_here.

Pour les détails complets d’implémentation, des exemples de code et les bonnes pratiques de sécurité, consultez le guide d’authentification OAuth2.

Structure de l’URL de base

La REST API de WordPress.com fournit une structure d’URL de base standardisée qui garantit un accès cohérent pour tous les types de sites, configurations d’hébergement et espaces de noms d’API. Tous les endpoints disponibles sont organisés et regroupés sous différents espaces de noms (tels que wp, rest et wpcom) et leurs versions respectives (comme v1, v1.4, v2, v4), offrant une séparation logique entre les différentes fonctionnalités de l’API et permettant des stratégies de versionnement indépendantes. Cette approche unifiée simplifie l’intégration de l’API et élimine la nécessité de déterminer différents formats d’URL en fonction des caractéristiques du site ou des versions de l’API.

Pour des informations détaillées sur les espaces de noms disponibles, leurs versions et les endpoints fournis par chaque espace de noms, consultez la documentation Espaces de noms et versions.

Structure générale de l’URL

Tous les endpoints de la REST API WordPress.com suivent ce modèle standardisé :

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

Paramètres fictifs :

• {namespace} : L’espace de noms de l’API (par ex., ‘rest’, ‘wp’, ‘wpcom’)
• {version} : La version de l’API (par ex., ‘v1’, ‘v1.4’, ‘v2’, ‘v4’)
• {endpoint} : Le point de terminaison spécifique de l’API auquel vous souhaitez accéder

Exemples :

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

Structure d’URL spécifique au site

Lorsque vous accédez à des points de terminaison qui opèrent sur des sites WordPress.com spécifiques, la structure d’URL inclut un identifiant de site :

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

Paramètres :

• {namespace} : L’espace de noms de l’API (par ex., ‘rest’, ‘wp’, ‘wpcom’)
• {version} : La version de l’API (par ex., ‘v1’, ‘v1.4’, ‘v2’, ‘v4’)
• {site_id} : L’identifiant numérique unique de votre site WordPress.com
• {endpoint} : Le point de terminaison spécifique lié au site (par ex., ‘posts’, ‘pages’, ‘media’, ‘users’)

Exemples :

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

Obtenir l’ID de votre site

Pour utiliser les endpoints spécifiques à un site, vous devez obtenir l’identifiant numérique unique de votre site. Vous pouvez obtenir cette information en effectuant une requête vers l’endpoint /rest/v1.1/me/sites depuis la console API :

1. Rendez-vous sur la console API WordPress.com
2. Naviguez vers l’endpoint /rest/v1.1/me/sites (qui se trouve sous WP.COM API - v1.1/me/sites dans la console)
3. Exécutez la requête pour récupérer tous les sites associés à votre compte
4. Repérez le champ ID dans la réponse pour le site souhaité

L’endpoint /rest/v1.1/me/sites renvoie des informations détaillées sur tous les sites associés à votre compte WordPress.com, notamment :

• ID : L’identifiant numérique unique du site (ce dont vous avez besoin pour les appels API)
• name : Le nom affiché du site
• URL : L’URL publique du site
• jetpack : Si le site est un site connecté via Jetpack
• is_private : Si le site est privé
• capabilities : Les actions que vous pouvez effectuer sur le site

Exemple de réponse :

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

Formats d’URL alternatifs

Vous pouvez rencontrer certains formats d’URL alternatifs :

• Accès direct au site, comme https://yoursite.com/wp-json/wp/v2/posts – Ce format fonctionne uniquement pour les sites auto-hébergés avec Jetpack. Peut échouer en raison de paramètres de sécurité, de règles de pare-feu ou de problèmes d’authentification.
• Accès WordPress.com basé sur le domaine, comme https://public-api.wordpress.com/wp/v2/sites/yoursite.com/posts – Ce format n’est pas fiable pour les sites avec des domaines personnalisés, des configurations DNS, ou lorsque les domaines changent.

Pour éviter tout problème, l’approche recommandée est d’utiliser le format avec les ID numériques de site, qui est plus fiable, plus rapide, fonctionne de manière cohérente sur tous les types de sites et prend en charge l’ensemble des fonctionnalités et méthodes d’authentification de WordPress.com.

Exigences d’authentification

L’API REST WordPress.com prend en charge les requêtes authentifiées et non authentifiées, selon le point de terminaison et les données auxquelles vous essayez d’accéder. Comprendre quand et comment s’authentifier est essentiel pour une intégration API réussie.

Les requêtes non authentifiées fonctionnent pour :

• Les informations publiques du site (par ex., détails du site, articles publics)
• La lecture de contenu public depuis les sites WordPress.com
• L’accès aux statistiques et données disponibles publiquement

Exemples de requêtes non authentifiées :

# 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

L’authentification est requise pour :

• Créer, modifier ou supprimer du contenu (articles, pages, commentaires)
• Accéder à des sites privés ou à du contenu privé
• Gérer les réglages et la configuration du site
• Accéder aux données spécifiques à l’utilisateur (notifications, sites suivis, statistiques personnelles)
• Toute opération qui nécessiterait qu’un utilisateur soit connecté lors de l’utilisation directe de WordPress.com

Exemples de requêtes authentifiées (nécessitent un jeton) :

# 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éthodes d’authentification

Toute authentification via la REST API de WordPress.com repose sur des jetons. Chaque requête authentifiée nécessite un jeton d’accès OAuth2 obtenu auprès des points de terminaison OAuth2 de WordPress.com. Les méthodes les plus pertinentes pour obtenir ces jetons sont :

• Échange direct de jetons par identifiants (pour un usage personnel et le développement)
• Flux OAuth2 complet (recommandé pour les applications tierces)

Échange direct de jetons par identifiants

Les mots de passe d’application offrent un raccourci pour obtenir des jetons d’accès OAuth2 sans implémenter le flux complet d’autorisation utilisateur. Cette méthode utilise le flux OAuth2 grant_type=password pour échanger directement votre nom d’utilisateur WordPress.com et votre mot de passe d’application contre un jeton d’accès.

Quand utiliser cette méthode :

• Projets personnels et développement
• Outils et scripts en ligne de commande
• Applications qui accèdent uniquement à vos propres sites WordPress.com
• Tests et prototypage

Comment ça fonctionne : Au lieu de rediriger les utilisateurs via l’interface d’autorisation de WordPress.com, vous utilisez votre mot de passe d’application pour demander directement un jeton depuis le point de terminaison OAuth2. Cela contourne l’étape de consentement de l’utilisateur mais nécessite vos véritables identifiants WordPress.com.

Comment utiliser l’échange direct de jeton par identifiants :

Pour utiliser cette méthode, vous devrez :

• Créer une nouvelle application WordPress.com pour obtenir le Client ID et le Client Secret de votre application.
• Si l’authentification à deux facteurs est activée (fortement recommandé), créez un nouveau mot de passe d’application. Sinon, utilisez votre mot de passe habituel.

Cette méthode utilise le flux OAuth2 grant_type=password pour échanger directement votre mot de passe d’application contre un jeton d’accès :

# 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"}'

Points clés :

• Les mots de passe d’application ne sont jamais utilisés directement avec les points de terminaison public-api.wordpress.com
• Ils sont uniquement utilisés avec le point de terminaison de jeton OAuth2 pour obtenir des jetons d’accès
• Le jeton obtenu est identique aux jetons obtenus via le flux OAuth2 complet
• Toutes les requêtes API suivantes utilisent le jeton OAuth2, et non le mot de passe d’application

Flux OAuth2 complet

Le flux OAuth2 complet est l’approche recommandée pour les applications tierces qui nécessitent que les utilisateurs autorisent l’accès à leurs sites et données WordPress.com. Cette méthode offre le système de permissions le plus sécurisé et le plus granulaire.

Quand utiliser cette méthode :

• Applications tierces accédant aux données des utilisateurs
• Applications web avec plusieurs utilisateurs
• Applications mobiles
• Toute application nécessitant des permissions contrôlées par l’utilisateur

Comment ça fonctionne : Les utilisateurs sont redirigés vers WordPress.com où ils peuvent examiner et autoriser les permissions spécifiques que votre application demande. Après l’autorisation, votre application reçoit un jeton d’accès qui peut être utilisé pour effectuer des requêtes API au nom de l’utilisateur.

Résumé du flux OAuth2 complet :

1. Enregistrez votre application sur WordPress.com Apps pour obtenir votre client ID et votre secret
2. Redirigez les utilisateurs vers l’URL d’autorisation de WordPress.com avec votre client ID et les scopes demandés
3. L’utilisateur examine et accorde la permission via l’interface de WordPress.com
4. WordPress.com redirige vers votre application avec un code d’autorisation
5. Échangez le code d’autorisation contre un jeton d’accès OAuth2 en utilisant votre client secret
6. Utilisez le jeton d’accès OAuth2 dans toutes les requêtes API avec Authorization: Bearer YOUR_TOKEN

Le résultat est le même format de jeton d’accès OAuth2 que celui utilisé par la méthode d’échange direct de jetons par identifiants, garantissant une authentification cohérente entre les deux approches.

Pour des conseils détaillés sur l’implémentation OAuth2, y compris des exemples de code et des considérations de sécurité, consultez la documentation OAuth2 Authentication.

Dépannage de l’authentification et bonnes pratiques

Erreurs d’authentification courantes

401 Unauthorized

• Cause : Jeton d’accès invalide ou manquant
• Solution : Vérifiez que votre jeton est correct et inclus dans l’en-tête Authorization

403 Forbidden

• Cause : Jeton valide mais permissions insuffisantes pour l’action demandée
• Solution : Vérifiez que votre compte utilisateur dispose des capacités nécessaires pour le site

Format de jeton invalide

• Cause : Format d’en-tête incorrect
• Solution : Assurez-vous d’utiliser Authorization: Bearer YOUR_TOKEN (notez l’espace après « Bearer »)

Bonnes pratiques de sécurité

1. N’exposez jamais les identifiants dans le code côté client – Les mots de passe d’application ne doivent être utilisés que dans les applications côté serveur
2. Utilisez des variables d’environnement – Stockez les noms d’utilisateur et les mots de passe dans des variables d’environnement, pas dans votre code source
3. Renouvelez régulièrement les mots de passe – Générez périodiquement de nouveaux mots de passe d’application et révoquez les anciens
4. Utilisez OAuth2 pour les applications destinées aux utilisateurs – N’utilisez pas les mots de passe d’application pour les applications avec lesquelles d’autres utilisateurs s’authentifieront
5. Comprenez le système de jetons unifié – Les deux méthodes d’authentification aboutissent aux mêmes jetons d’accès OAuth2, offrant un accès API et une sécurité cohérents
6. Choisissez la bonne méthode – Utilisez le raccourci Mot de passe d’application pour un usage personnel ou de développement, et le flux OAuth2 complet pour les applications tierces
7. Gestion des jetons – Les jetons peuvent être révoqués par application sans affecter les autres applications, offrant une meilleure sécurité que le partage de mots de passe

Applications basées sur le navigateur

Si vous développez une application basée sur le navigateur, vous devrez :

1. Utilisez le flux implicite OAuth2 – Les mots de passe d’application ne doivent pas être utilisés dans le code côté client
2. Ajoutez vos domaines à la liste blanche – Configurez les origines autorisées dans les paramètres de votre application WordPress.com
3. Gérez correctement le CORS – L’API enverra les en-têtes CORS appropriés pour les domaines autorisés

Pour des conseils détaillés sur les implémentations côté navigateur, consultez Utiliser la REST API depuis JS et le navigateur.

Ressources et documentation

• Console API – Tests interactifs et exploration
• Référence de l’API – Documentation complète des points de terminaison
• Manuel de la REST API WordPress – Documentation officielle de la REST API du cœur de WordPress
• Blog développeurs – Mises à jour et annonces concernant les modifications de l’API