Utiliser l’API HTTP de WordPress

L’API HTTP de WordPress se compose d’un tas de fonctions qui vous aideront à faire des appels HTTP beaucoup plus facilement. Plus besoin de bidouiller avec file_get_contents ou cURL, juste une seule interface unifiée. C’est génial pour interagir avec les API tierces, en particulier les REST API comme Twitter, Facebook, MailChimp et d’autres.

• Les bases du HTTP
• À propos des API Restful
• Utilisation de l’API HTTP de WordPress

Les bases du HTTP

Nous avons tous déjà vu HTTP en action. En fait, si c’est votre toute première visite sur le web et que c’est la première chose que vous lisez, vous avez déjà vu HTTP faire sa magie. HTTP est un protocole réseau utilisé pour livrer tous les fichiers et toutes les données (ressources) sur Internet.

Il y a essentiellement deux parties à l’équation : la requête HTTP et la réponse HTTP, ou transaction. La requête et la réponse ont une structure très similaire, elles comportent toutes deux quatre parties :

• Une ligne initiale
• Zéro ligne d’en-tête ou plus
• Une ligne vide
• Un contenu de corps facultatif

La ligne initiale

Les requêtes utilisent la ligne initiale pour envoyer trois informations : le nom de la méthode, le chemin et la version HTTP. Par exemple, en consultant la page principale du blog Kinsta, vous verrez ceci dans la ligne initiale de la requête.

GET /blog/ HTTP/1.1

Les réponses fournissent également trois éléments d’information, bien qu’ils soient quelque peu différents : La version HTTP, le code de réponse et une description de la réponse. Lorsque vous faîtes une requête au blog principal de Kinsta, celui-ci envoie une réponse HTTP avec la ligne initiale suivante :

HTTP/1.0 200 OK

Les en-têtes

Les en-têtes contiennent divers éléments d’information sur la requête ou la réponse. HTTP 1.1 définit 46 types d’en-têtes mais un seul est obligatoire (uniquement pour les requêtes), l’en-tête « Host ». Regardez la capture d’écran de mes outils de développement Chrome qui montre certains des en-têtes envoyés avec une requête au blog principal de Kinsta :

Corps

Le corps contient généralement des données sur la ressource demandée. Si vous envoyez une requête GET au blog principal de Kinsta, vous devriez recevoir le HTML nécessaire pour rendre la page (la ressource) dans le contenu du corps.

Plus d’informations

C’est tout ce que vous avez besoin de savoir pour l’instant sur HTTP. Nous nous concentrerons principalement sur le nom de la méthode (GET,POST,etc), les en-têtes et le corps. Si vous voulez en savoir plus, je vous recommande l’explication de HTTP par James Marshall, c’est une introduction très bien écrite pour vos besoins en HTTP.

À propos des API Restful

Les API Restful, ou la méthodologie REST, ont pour but de fournir un moyen simple et standard d’interagir avec une application (vous pouvez en savoir plus sur les bases de l’API REST de WordPress). Elle est souvent utilisée en conjonction avec HTTP pour créer un système d’interactions très compréhensible. Elle est basée sur les chemins et les verbes HTTP.

Les verbes HTTP sont les mêmes que les noms de méthodes que nous avons vus précédemment, les plus courants sont : GET, POST, PUT, DELETE. Je pense que PUT est le seul verbe ambigu ici, considérez-le comme une commande de mise à jour. En utilisant ces verbes avec des chemins, nous pouvons construire un système significatif :

GET /post/1/ serait utilisé pour récupérer l’article avec l’ID de 1. DELETE /post/1/ serait utilisé pour supprimer le même article. Nous pourrions également utiliser PUT /post/1/ pour le mettre à jour, en fournissant des informations pertinentes dans le corps de la requêtes et les en-têtes.

Je suis sûr que vous pouvez voir que juste en ajoutant une version HTTP à nos codes ci-dessus, nous avons en fait la ligne initiale d’une transaction HTTP, ce qui n’est qu’une des raisons pour lesquelles ce système est si puissant.

Utiliser l’API HTTP de WordPress

Armés de toutes ces connaissances, nous pouvons facilement comprendre comment fonctionne l’API HTTP de WordPress. Les quatre méthodes utilisées pour faire des requêtes et intercepter les réponses sont les suivantes :

• wp_remote_get()
• wp_remote_post()
• wp_remote_head()
• wp_remote_request()

Les deux premières fonctions sont auto-explicatives, elles utilisent respectivement les méthodes GET et POST dans la requête. La troisième fonction utilise la méthode HEAD, dont nous n’avons pas encore parlé. Cette méthode est utilisée pour récupérer uniquement les en-têtes d’une réponse. Cela peut permettre d’économiser beaucoup de ressources si nous avons juste besoin de quelques métadonnées sur une ressource. La dernière fonction est une fonction générique, vous pouvez spécifier la méthode que vous souhaitez utiliser dans les paramètres de la fonction.

Il existe cinq fonctions supplémentaires que nous pouvons utiliser pour récupérer des parties spécifiques de la réponse. Ce sont essentiellement des raccourcis pour naviguer dans la masse de données que nous recevons :

• wp_remote_retrieve_body()
• wp_remote_retrieve_header()
• wp_remote_retrieve_headers()
• wp_remote_retrieve_response_code()
• wp_remote_retrieve_response_message()

Notre première requête HTTP

Faisons un test rapide en récupérant les informations d’en-tête du blog Kinsta. Vous pouvez faire cela n’importe où dans une extension ou un thème, mais vous devez évidemment vous trouver dans un environnement de test pour vous assurer que vous n’envoyez pas de texte indésirable sur un site en production.

$response = wp_remote_head( 'https://kinsta.com/blog/' );
var_dump( $response )

Comme vous pouvez le voir dans la réponse que nous obtenons ci-dessous, la section body est vide (puisque nous utilisons la méthode HEAD) et tous les en-têtes sont affichés. Pour récupérer uniquement les en-têtes sans tous les autres membres du tableau, nous pouvons utiliser la fonction wp_remote_retrieve_headers().

array (size=5)
  'headers' => 
    array (size=13)
      'server' => string 'nginx' (length=5)
      'date' => string 'Wed, 22 Jul 2015 14:22:07 GMT' (length=29)
      'content-type' => string 'text/html; charset=UTF-8' (length=24)
      'connection' => string 'close' (length=5)
      'vary' => string 'Accept-Encoding' (length=15)
      'x-pingback' => string 'https://kinsta.com/xmlrpc.php' (length=29)
      'x-powered-by' => string 'HHVM/3.8.0' (length=10)
      'link' => string '; rel="https://github.com/WP-API/WP-API"' (length=68)
      'x-frame-options' => string 'DENY' (length=4)
      'x-content-type-options' => string 'nosniff' (length=7)
      'strict-transport-security' => string 'max-age=31536000' (length=16)
      'x-kinsta-cache' => string 'HIT' (length=3)
      'content-encoding' => string 'gzip' (length=4)
  'body' => string '' (length=0)
  'response' => 
    array (size=2)
      'code' => int 200
      'message' => string 'OK' (length=2)
  'cookies' => 
    array (size=0)
      empty
  'filename' => null

Comprendre les API

Le plus gros obstacle que je vois pour les développeurs est la quantité de nouvelles choses qu’ils doivent mettre en place pour qu’un appel d’API fonctionne. Vous devez connaître HTTP, comment faire des requêtes et aussi comment vous authentifier correctement, sans cela, chaque appel échouera. Regardons un exemple à travers l’API de Twitter puisqu’ils ont une excellente documentation.

Nous allons examiner l’authentification uniquement par application (qui est un flux plus facile), je vais suivre les mêmes étapes que celles proposées par Twitter. Avant de commencer, assurez-vous de créer une application Twitter.

Vous devriez pouvoir ajouter le code ci-dessous n’importe où dans un thème ou une extension mais, comme précédemment, assurez-vous d’utiliser un site de test !

Étape 1 : Encoder la clé et le secret du consommateur

Une fois que vous avez créé une application, vous devriez avoir une clé et un secret du consommateur à portée de main. Pour faciliter les choses, créons des constantes qui détiennent ces informations pour nous.

define( 'TWITTER_CONSUMER_KEY', '12disnir382jeqwdasd23wdasi' ) ;
define( 'TWITTER_CONSUMER_SECRET', '23wdajskduhtrq2c32cuq9r8uhuf' )

Les trois étapes de la création d’une version codée de ces constantes sont présentées dans la documentation :

• Codage URL de la clé du consommateur et du secret du consommateur
• Concatenez-les avec deux points
• Encodez la chaîne entière en Base64

En PHP, ce sera assez facile à faire, c’est parti !

$key = urlencode( TWITTER_CONSUMER_KEY ) ;
$secret = urlencode( TWITTER_CONSUMER_SECRET ) ;
$concatenated = $key . ':' . $secret ;
$encoded = base64_encode( $concatenated ) ;

Étape 2 : Obtenir un jeton porteur (Bearer)

Au lieu d’utiliser votre mot de passe réel, vous envoyez à Twitter votre chaîne codée (qui utilise vos informations d’identification API) et vous recevez un jeton temporaire qui est valable pendant une durée déterminée. Pour cela, nous allons faire une requête HTTP, voici ce que Twitter a à dire :

• La requête doit être une requête HTTP POST.
• La requête doit inclure un en-tête Authorization avec la valeur Basic .
• La requête doit inclure un en-tête Content-Type avec la valeur de application/x-www-form-urlencoded;charset=UTF-8.
• Le corps de la requête doit être grant_type=client_credentials.

Commençons par les bases. Nous savons que nous avons besoin d’une requête POST et nous utiliserons donc wp_remote_post(). La fonction prend deux paramètres; le premier est l’URL, le second contient des arguments facultatifs. L’URL sera https://api.twitter.com/oauth2/token, nous utiliserons le deuxième paramètre pour gérer tous les autres besoins.

$args = array(
    'headers' => array(
        'Authorization' => 'Basic ' . $encoded,
        'Content-Type' => 'application/x-www-form-urlencoded;charset=UTF-8'
    ),
    'body' => 'grant_type=client_credentials'
);
$response = wp_remote_post( 'https://api.twitter.com/oauth2/token', $args );

Les en-têtes doivent être ajoutés sous forme de tableau, le type d’en-tête étant la clé, la valeur étant la valeur du membre du tableau; Le corps doit être une chaîne. En cas de succès, vous devriez voir une réponse similaire à celle ci-dessous.

array (size=5)
  'headers' => 
    array (size=23)
      'cache-control' => string 'no-cache, no-store, must-revalidate, pre-check=0, post-check=0' (length=62)
      'content-disposition' => string 'attachment; filename=json.json' (length=30)
      'content-encoding' => string 'deflate' (length=7)
      'content-length' => string '142' (length=3)
      'content-type' => string 'application/json;charset=utf-8' (length=30)
      'date' => string 'Wed, 22 Jul 2015 14:47:37 GMT' (length=29)
      'expires' => string 'Tue, 31 Mar 1981 05:00:00 GMT' (length=29)
      'last-modified' => string 'Wed, 22 Jul 2015 14:47:37 GMT' (length=29)
      'ml' => string 'A' (length=1)
      'pragma' => string 'no-cache' (length=8)
      'server' => string 'tsa_b' (length=5)
      'set-cookie' => string 'guest_id=v1%3A14375720938219946; Domain=.twitter.com; Path=/; Expires=Fri, 21-Jul-2017 14:47:37 UTC' (length=100)
      'status' => string '200 OK' (length=6)
      'strict-transport-security' => string 'max-age=631138519' (length=17)
      'x-connection-hash' => string 'd8b10926f99dwef93rd7edbe5a71a97a' (length=32)
      'x-content-type-options' => string 'nosniff' (length=7)
      'x-frame-options' => string 'SAMEORIGIN' (length=10)
      'x-response-time' => string '34' (length=2)
      'x-transaction' => string 'ef0ebwefweece62ef' (length=16)
      'x-tsa-request-body-time' => string '0' (length=1)
      'x-twitter-response-tags' => string 'BouncerCompliant' (length=16)
      'x-ua-compatible' => string 'IE=edge,chrome=1' (length=16)
      'x-xss-protection' => string '1; mode=block' (length=13)
  'body' => string '{"token_type":"bearer","access_token":"AAAAAAAAAAAAAAAAAAAAAFoafQAAAAAAqg%2BxmuH83hjsod6crH5bKTUX9Arc%3D5dWpp0XCTDjyiXxMC7LDLg8JbzPdGlCsJi2R1qjY1FMksTAFyG"}' (length=155)
  'response' => 
    array (size=2)
      'code' => int 200
      'message' => string 'OK' (length=2)
  'cookies' => 
    array (size=1)
      0 => 
        object(WP_Http_Cookie)[303]
          public 'name' => string 'guest_id' (length=8)
          public 'value' => string 'v1:143757645770219946' (length=21)
          public 'expires' => int 1500648457
          public 'path' => string '/' (length=1)
          public 'domain' => string '.twitter.com' (length=12)
  'filename' => null

Le point fort de tout cela est le jeton d’accès qui se trouve dans le corps de la réponse. Récupérons-le maintenant à l’aide des fonctions pratiques de WordPress. En continuant avec notre exemple précédent, nous pourrions récupérer le jeton d’accès en utilisant le code suivant:

$body = wp_remote_retrieve_body( $response );
$body = json_decode( $body, true );
$access_token = $body['access_token'];

Étape 3 : Utiliser le jeton porteur (bearer)

La dernière étape consiste simplement à utiliser ce jeton porteur dans tous les autres appels d’API. Nous devons l’ajouter en tant qu’en-tête « Authorization » avec la valeur : Bearer [bearer_token]. Faisons un appel d’API simple qui récupérera les derniers tweets d’un utilisateur en utilisant le chemin user_timeline.

$url = 'https://api.twitter.com/1.1/statuses/user_timeline.json?screen_name=danielpataki&count=3';
$args = array(
    'headers' => array(
        'Authorization' => 'Bearer ' . $access_token,
    ),
);

$response = wp_remote_get( $url, $args );
$tweets = json_decode( wp_remote_retrieve_body($response), true )

À la fin de tout cela, la variable $tweets contiendra un tableau de tweets. Vous pouvez utiliser diverses propriétés de ce tableau pour afficher le tweet ou manipuler les données.

Conclusion

Comme vous pouvez le voir, utiliser l’API HTTP de WordPress pour se connecter à des services externes n’est pas si difficile. De nombreuses API modernes sont construites autour des mêmes principes REST – une fois que tu en avez appris une, vous vous familiariserez très vite avec les autres.

Gardez à l’esprit que chaque fois que la documentation vous demande d’utiliser le corps, utilisez le corps et lorsqu’elle demande des en-têtes, ajoutez-en autant que nécessaire. Ensuite, regardez la réponse, convertissez-la en tableau, récupèrez les données dont vous avez besoin et utilisez-les, c’est aussi simple que cela.

Si quelqu’un a déjà travaillé avec une API particulièrement bonne ou mauvaise, ou si vous avez des trucs et astuces pour utiliser l’API HTTP de WordPress, faîtes-le nous savoir dans les commentaires !

Daniel Pataki

Hi, my name is Daniel, I'm the CTO here at Kinsta. You may know me from Smashing Magazine, WPMU Dev, Tuts+ and other WordPress/Development magazines. Aside from WordPress and PHP I spend most of my time around Node, React, GraphQL and other technologies in the Javascript space.

When not working on making the best hosting solution in the Universe I collect board games, play table football in the office, travel or play guitar and sing in a pretty bad band.

• Site Web
• Twitter