Share
Depuis sa création en 2003, WordPress est passé d’une plate-forme de blogs à un système de gestion de contenu à part entière. Au cours de ces dernières années, il a suffisamment mûri pour répondre aux besoins d'une vaste majorité d'audience en ligne. C'est la raison pour laquelle il autonomise plus de 20% du Web aujourd'hui..
Avec de nombreuses nouvelles fonctionnalités ajoutées à WordPress, l’un des derniers ajouts est l’API REST qui permet à d’autres applications et plates-formes d’interagir avec WordPress. C'est un ajout révolutionnaire qui aidera les développeurs à créer des applications personnalisées et des systèmes intégrés avec WordPress. Puisqu'il offre la possibilité d'ajouter et de récupérer du contenu à partir de tout autre client ou site, sans qu'il soit nécessaire d'installer WordPress sur ce site, il permet d'utiliser WordPress avec n'importe quel langage ou plate-forme de programmation..
Dans cette série en plusieurs parties, nous allons examiner l'API WP REST et la manière dont elle pourrait être utilisée pour créer des expériences utilisateur autrement impossibles ou du moins ardues avec WordPress. Nous allons d'abord examiner les concepts de base, notamment REST et JSON, puis explorer les options disponibles via l'API WP REST..
Vous trouverez ci-dessous quelques ressources utiles pour les concepts de base, notamment HTTP, REST et JSON. Je vous recommande fortement de les regarder si vous ne l'avez pas déjà fait:
Avant de commencer notre sujet, jetons un bref aperçu de l’architecture REST et familiarisons-nous également avec sa terminologie commune..
Pour commencer avec le sujet, jetons un coup d’œil au REST (Réprésentation State Ttransfert) de l’architecture et de certains de ses concepts les plus courants. Leur compréhension est essentielle lors du développement d'applications utilisant le style architectural REST..
REST est un style architectural qui aide à créer et à organiser un système distribué. Il décrit le Web comme une application hypermédia distribuée dont les ressources liées communiquent en échangeant des représentations de Ressource Etat.
Les ressources sont les principaux composants de l’architecture REST. En fait, ils sont les principaux éléments constitutifs du Web lui-même, dans la mesure où il est parfois appelé «orienté ressources»..
Lorsque vous parlez de WordPress, ces ressources sont des entités discrètes telles que des publications, des pages, des commentaires, des utilisateurs et des types de publication personnalisés, etc. Pour interagir avec des ressources, URI (Uniform Resource Identifier) sont utilisés et, comme son nom l’indique, c’est un identifiant pour une ressource..
Un service RESTful considère les URI comme le moyen principal de traiter une ressource sous-jacente. Ces ressources peuvent avoir plusieurs représentations. Par exemple, un fichier image peut être disponible aux formats .JPG, .GIF ou .PNG. La relation entre les ressources et les URI est un à plusieurs. Un URI ne peut pointer que vers une ressource spécifique, mais une ressource peut avoir plusieurs URI..
La liste de toutes les ressources actuellement prises en charge par l'API WP REST est la suivante:
Nous pouvons effectuer différentes actions sur ces ressources en utilisant des verbes HTTP.
Une API REST permet en principe d’effectuer des opérations CRUD (Create Read Update Delete) sur des ressources via HTTP. Pour ce faire, REST utilise un ensemble limité de verbes de requête HTTP, qui sont les suivants:
Accentsconagua
OBTENIR: Utilisé pour lire ou récupérer une ressourcePOSTER: Utilisé pour créer une nouvelle ressourceMETTRE: Utilisé pour mettre à jour une ressourceEFFACER: Utilisé pour supprimer une ressourceTÊTE: Utilisé pour vérifier si une ressource existe sans retourner sa représentationOPTIONS: Utilisé pour récupérer tous les verbes supportés par une ressourceDans un service RESTful, ces verbes ont des significations bien définies. Les quatre premiers verbes de la liste ci-dessus font partie des actions CRUD, c’est-à-dire qu’ils récupèrent, créent, mettent à jour et suppriment des entités. Les deux derniers verbes aident un client à déterminer si une ressource existe et quels verbes HTTP sont disponibles pour effectuer d'autres opérations..
UNE OBTENIR request récupère les informations et est idempotent si un client peut l’appeler plusieurs fois mais cela n’affectera pas l’état d’une ressource.
Pour obtenir tous les articles à l’aide de l’API WP REST, nous utilisons les éléments suivants: point final:
GET wp / v2 / posts
Le point final ci-dessus retournera un collection de toutes les entités postales.
Lorsque le noeud final suivant est déclenché, il renvoie un message particulier. entité c'est-à-dire un message ayant un identifiant de 100:
GET wp / v2 / posts / 100
UNE POSTER demande crée une nouvelle entité et un METTRE request remplace cette entité par une nouvelle version.
Le suivant POSTER request peut être utilisé pour créer une nouvelle publication (envoi du corps de la requête que nous verrons dans la dernière partie de la série) à l'aide de l'API WP REST:
POST wp / v2 / posts
Et les suivants METTRE request mettra à jour un message dont l'identifiant est 100:
PUT wp / v2 / posts / 100
UNE EFFACER request supprime une ressource du système. Ce type de demande, avec METTRE request sont répétables, ce qui signifie que l'appel de ces méthodes aura le même effet sur le système. Par exemple, si vous appelez un METTRE demander plusieurs fois sur une ressource (avec les mêmes arguments), le résultat sera le même. La même chose vaut pour un EFFACER demande. La suppression répétée d’une ressource aura le même effet, c’est-à-dire que la ressource sera supprimée (ou qu’une erreur serait renvoyée dans le cas d’une ressource déjà supprimée)..
En plus de ces actions CRUD, un service RESTful fournit deux autres verbes qui sont OPTIONS et TÊTE. Ces verbes sont pratiques lorsqu'un client doit vérifier quelles ressources sont disponibles sur le système et quelles actions ils prennent en charge, offrant ainsi au client un moyen d'auto-documentation lui permettant d'explorer plus à fond le système et d'effectuer des actions. Nous verrons ces deux méthodes en action plus tard dans ce tutoriel..
Notez que dans le tout premier exemple ci-dessus, nous avons utilisé ce qui suit point final:
GET wp / v2 / posts
Les points de terminaison sont des fonctions disponibles via l'API. Ils effectuent plusieurs opérations, telles que la récupération de publications (que nous effectuons précédemment), la création d'un nouvel utilisateur ou la mise à jour d'un méta de publication. Alternativement, nous pouvons dire qu'un noeud final déclenche une méthode qui effectue une tâche spécifique. Ces points de terminaison dépendent du verbe HTTP qui leur est associé. Dans l'exemple ci-dessus, nous utilisons le verbe GET pour récupérer tous les messages..
le route pour le point final ci-dessus est la suivante:
wp / v2 / posts
Un itinéraire est fondamentalement un nom pour accéder au noeud final. Une route peut avoir plusieurs noeuds finaux basés sur des verbes HTTP. La route ci-dessus dispose donc du point de terminaison suivant pour créer une nouvelle publication:
POST wp / v2 / posts
Ce terminal, lorsqu'il est déclenché avec les paramètres fournis, créera une nouvelle entité de publication..
Considérez l'itinéraire suivant:
wp / v2 / posts / 100
Cet itinéraire pointe vers l'entité Post ayant un identifiant de 100. Il comporte les trois extrémités suivantes:
GET wp / v2 / posts / 100: Qui peut être utilisé pour récupérer le poste ayant un identifiant de 100. Il déclenche le obtenir l'article() méthode.PUT wp / v2 / posts / 100: Peut être utilisé pour mettre à jour le message ayant un identifiant de 100. Il déclenche le update_item () méthode.SUPPRIMER wp / v2 / posts / 100: Il supprime le poste ayant un identifiant de 100. Il déclenche le effacer l'article() méthode.Nous en apprendrons davantage sur les composants internes de l'API WP REST, sa structure de classe et ses méthodes internes dans la dernière partie de cette série..
Actualisons maintenant nos connaissances sur certains codes de réponse HTTP courants et leur signification..
Un serveur répond à une demande en renvoyant une réponse contenant un code d'état HTTP. Ces codes sont des nombres avec des significations prédéfinies qui leur sont associées. Par exemple, toute personne utilisant le Web connaîtrait bien le 404 code de statut qui résume que la ressource, l'utilisateur cherchait, était introuvable.
La réponse du serveur dépend également du type de verbe HTTP ou de la méthode que nous utilisons dans la requête envoyée, comme nous le verrons plus loin..
Voici quelques codes de réponse HTTP courants avec leur signification, que nous rencontrerons lorsque nous utiliserons l'API WP REST, ainsi que leur signification:
200 - OK: Signifie que la demande a été complétée avec succès et que le serveur a renvoyé la réponse. Habituellement retourné après un succès OBTENIR demande.201 - Créé: Généralement retourné après un succès POSTER demande. Résume que la ressource a été créée.400 - Mauvaise demande: Il est renvoyé par le serveur lorsqu'une demande a été envoyée avec des paramètres manquants ou non valides. Habituellement retourné en réponse à POSTER ou METTRE demandes.401 - non autorisé: Signifie que l'utilisateur n'était pas autorisé à effectuer certaines actions. Par exemple, un utilisateur a tenté de créer ou de supprimer une ressource sans fournir les informations d'authentification..403 - Interdit: Signifie que le serveur a compris la requête mais a refusé de la compléter en raison de son authentification. Cela se produit lorsqu'un utilisateur fournit des informations d'authentification mais qu'il ne dispose pas des droits suffisants pour effectuer l'action..404 - introuvable: Le plus célèbre des codes de statut. Résume que la ressource recherchée par l'utilisateur n'a pas été trouvée.405 - Méthode non autorisée: Signifie qu'un verbe HTTP fourni dans la demande n'était pas pris en charge par la ressource. Un exemple pourrait être un utilisateur essayant de mettre à jour une ressource en lecture seule.410 - parti: Signifie qu'une ressource a été déplacée vers un autre emplacement. Vous pouvez par exemple essayer de supprimer une ressource déjà supprimée qui a été déplacée vers la corbeille.500 - Erreur interne du serveur: Il est renvoyé lorsqu'un serveur rencontre une condition inattendue et ne termine pas la demande.501 - Non implémenté: Signifie que le serveur ne prend pas en charge la fonctionnalité permettant de compléter la demande. Cela se produit généralement lorsqu'un serveur reçoit une méthode de requête qu'il ne reconnaît pas..Nous examinerons de plus près ces verbes HTTP et codes de réponse lorsque nous commencerons à travailler avec l'API. Mais avant cela, examinons les raisons d'utiliser l'API REST avec WordPress et les avantages qu'elle procure au développeur et à l'utilisateur. Après tout, il faut que vous soyez véritablement intéressé à suivre avec moi pendant cette série.
Ensemble, REST et JSON constituent un mécanisme permettant de créer des applications puissantes utilisant le back-end WordPress. Les exemples les plus importants sont les applications mobiles qui nécessitent l’échange de données entre le client (le périphérique) et le serveur. Gardant à l'esprit les limitations de bande passante lors de l'utilisation de données cellulaires, JSON fournit une alternative légère aux solutions basées sur XML..
Étant donné que JSON est un format texte pour le stockage de données, il peut être utilisé de manière transparente avec la plupart des langages de programmation. JSON sert donc de connecteur global lors de l'échange de données entre différentes plates-formes, lisible de manière égale par les machines et les humains..
Avec l’utilisation d’API comme celle dont il est question, le contenu de votre site WordPress ne se limite pas à lui-même mais peut être consulté par d’autres sites et clients. Comme l'API expose certaines parties de la fonctionnalité interne, les clients distants peuvent interagir avec votre site pour mettre à jour ou créer un nouveau contenu. Il permet également de récupérer du contenu d’un site WordPress existant et de l’afficher sur un autre site..
Avec la montée en puissance des frameworks JavaScript côté client tels que Angular, Backbone ou Ember, il est désormais possible d’utiliser l’un d’eux pour créer des expériences utilisateur enrichies tout en utilisant le back-end WordPress..
Cela dit, voici quelques exemples d'utilisation de l'API WP REST:
Cela ouvre vraiment un nouveau monde de possibilités où la seule limite est l'imagination.
Avant les API REST basées sur JSON, l'API utilisée pour interagir à distance avec WordPress était l'API XML-RPC qui faisait toujours partie du cœur de WordPress. Le problème avec XML est qu’il n’est pas aussi léger que le format JSON et que son analyse n’est pas efficace. Traverser du XML est aussi un casse-tête, tandis que traverser un objet JSON est aussi simple que de manipuler un objet JavaScript natif.
Le tout premier plug-in API REST introduit pour WordPress était API JSON qui a été publié en 2009. Il a été construit au Musée d'Art Moderne pour leur blog Inside / Out. Le front-end de ce blog a été développé par Ruby on Rails, donc pour récupérer des publications et ajouter des commentaires au backend de WordPress, une API a été développée. Ce plugin fournit des interfaces pour récupérer du contenu et soumettre des commentaires au backend de WP. Bien que, non mis à jour depuis plus de deux ans, ce plugin est toujours présent dans le référentiel officiel et peut être récupéré..
Outre le plugin API JSON, WordPress.com fournit déjà une API JSON via le plugin JetPack..
L’API WP REST, telle que nous la connaissons aujourd’hui, est un plugin de fonctionnalités proposé par Ryan McCue dans le cadre de GsoC (Google Summer of Code) 2013. Il n’a pas encore été inclus (complètement) dans le noyau WordPress dans une version ultérieure. La version actuelle 2.0 du plugin est en version bêta et est partiellement incluse dans le noyau WordPress dans la version 4.4. C'est un projet mené par la communauté dirigé par Ryan McCue et Rachel Baker. La page du dépôt officiel du plugin se trouve sur GitHub et la documentation officielle est disponible sur son site web..
Comme mentionné ci-dessus, l'API WP REST est actuellement à l'état de plug-in et est activement développée sur GitHub. Il a été partiellement inclus dans le noyau WordPress dans la version 4.4 et Ryan a décrit le plan dans sa proposition de fusion sur WordPress.org..
Selon la proposition de fusion, l'API WP REST serait intégrée au noyau WP, en deux étapes, comme décrit ci-dessous:
Selon la proposition, au stade initial, seul le code de niveau d'infrastructure sera fusionné dans le noyau de WP dans la version 4.4. Ce code d'infrastructure constitue la base même de l'API WP REST, car il inclut la sérialisation / désérialisation JSON, la liaison, l'incorporation et le plus important de tous - la couche de routage qui pilote l'API. Ce code n'inclut pas les points de terminaison et leurs classes de contrôleur, mais il fournit une base pour la construction d'API dans WordPress..
Au moment de la rédaction de cet article, cet état était terminé et le code d'infrastructure avait été fusionné dans le noyau WordPress dans la version 4.4..
Les points de terminaison pour les publications, les pages, les utilisateurs, les taxonomies, etc. seront incorporés dans le noyau de WP dans la version 4.5, c'est-à-dire une version ultérieure à la fusion du code d'infrastructure. Ce sont les points finaux qui rendent l’API utile aux clients généraux. Ils comportent une grande complexité, notamment la mise en correspondance des données externes au format JSON avec les types de données WordPress natifs, et inversement. Ils représentent le code des deux tiers de l’API avec environ 5 500 lignes..
La stratégie consiste ici à renforcer la confiance des développeurs dans l'API en fournissant d'abord le code d'infrastructure dans le noyau. Cela permettrait aux développeurs de thèmes et de plugins de créer des API personnalisées à inclure dans leurs thèmes et plugins. Mais étant donné que les terminaux ne seront pas inclus à ce stade, cela limiterait l'utilité initiale de l'API.
L’écart entre les deux versions donnerait à l’équipe de committage principale de WP suffisamment de temps pour examiner les points de terminaison de l’API.
Un autre avantage que l'API WP REST apporterait à la communauté WordPress est l'utilisation de GitHub en version contrôlant le projet. Étant donné que toutes les contributions à WordPress sont apportées via SVN et Trac, l'équipe API WP REST est confiante quant à l'amélioration du processus de contribution en réduisant l'écart entre Trac et GitHub..
Après la fusion de l'API dans le noyau, nous pouvons espérer voir des développements rapides dans d'autres domaines, y compris l'authentification OAuth 1.0a..
Pour commencer les tests avec l'API WP REST, nous avons besoin d'un client HTTP qui sera utilisé pour envoyer des demandes au serveur et afficher la réponse. C'est vraiment une question de votre choix, mais j'utiliserai Postman pour Google Chrome au cours de cette série. Les autres alternatives à Postman sont:
Postman nous permet de créer des requêtes HTTP rapides de différentes méthodes, d'afficher la réponse du serveur et de tester la configuration pour l'authentification. Toutes ces fonctionnalités seront extrêmement utiles lorsque vous travaillerez avec l'API WP REST.
La prochaine chose dont nous avons besoin sur notre serveur est WP-CLI. Avec WP-CLI, nous pouvons gérer notre installation WordPress à distance depuis la console sans avoir à ouvrir la fenêtre du navigateur. Nous devrons utiliser WP-CLI dans la prochaine partie de cette série lors de la configuration de l'authentification OAuth 1.0a. Vous pouvez trouver les instructions d'installation sur le site officiel.
Outre un client HTTP et WP-CLI, nous avons également besoin de données de démonstration pour notre installation WordPress. Je suggère de vérifier le thème du test d'unité de thème (XML) ou le plug-in Demo Data Creator qui permet de créer plusieurs publications, pages et utilisateurs..
Au moment de la rédaction de ce didacticiel, la version stable actuelle est la 1.2.2, disponible sur le référentiel officiel. Dans cette série, nous allons travailler avec la version 2.0, car elle a été réécrite à partir de zéro et contient de nombreux changements décisifs. Vous pouvez récupérer la version bêta 2 depuis sa page officielle de plugin ou depuis son référentiel GitHub.
Veuillez noter qu'il est fortement déconseillé d'installer la version bêta actuelle sur votre environnement de production. J'ai mis en place un environnement WordPress local et je vous recommande de le faire à des fins de développement et de test.
Pour installer le plugin à partir du référentiel GitHub, ouvrez votre terminal et tirez le plugin après être entré dans votre / wp-content / plugins / annuaire:
$ git pull https://github.com/WP-API/WP-API.git
Le plugin sera téléchargé dans le / WP-API / annuaire.
Vous pouvez l'activer à partir de votre administrateur WordPress pour continuer à tester avec elle.
Pour que le plug-in WP REST API fonctionne, vous devez activer de jolis permaliens avec WordPress. On suppose ici que vous savez déjà effectuer cette action de base. Si vous ne le faites pas, pas de soucis, WordPress.org vous couvre.
Une fois le plugin installé, nous pouvons évaluer la disponibilité de l'API sur notre serveur. Nous ne sommes pas limités à utiliser l'API sur notre site uniquement. En fait, vous l'utilisez sur tout site sur lequel il est installé et activé. Pour vérifier l’API sur d’autres sites, nous pouvons envoyer une demande HEAD au site comme suit à l’aide de votre client HTTP:
$ HEAD http://someothersite.com/
Cela retournera quelque chose comme ceci dans l'en-tête de réponse:
le Lien header désigne la route racine de l'API WP, qui dans notre cas est la suivante:
http: // localserver / wordpress-api / wp-json /
L’API peut également être détectée via JavaScript dans le navigateur (ou jQuery) en interrogeant le DOM sur le logiciel approprié. élément comme celui-ci:
(fonction ($) var $ link = $ ('link [rel = "https://github.com/WP-API/WP-API"]'); var api_root = $ link.attr ('href') ;) (jQuery);À partir de là, nous pouvons commencer à récupérer le contenu du site via l’API WP REST. Veuillez noter que seules les requêtes authentifiées peuvent modifier ou mettre à jour le contenu du site et j'enregistre l'objet de la configuration de l'authentification pour les deux prochaines parties de cette série..
Dans cette partie introductive de la série, nous avons beaucoup appris sur l’architecture REST, l’API WP REST et le protocole HTTP lui-même. Nous avons d’abord examiné les concepts de base tels que l’architecture REST et comment elle peut aider les développeurs à créer de meilleures applications. Nous avons ensuite découvert HTTP, ses verbes et ses types de réponse. Nous avons également examiné un bref historique des API dans WordPress et expliqué en quoi l’API WP REST est différente de ses prédécesseurs..
Dans la dernière partie de ce tutoriel, nous avons installé le plugin de GitHub. Après cela, nous nous sommes familiarisés avec un TÊTE demande pouvant être utilisée pour déterminer la disponibilité de l'API sur notre serveur ainsi que sur d'autres serveurs.
Après avoir configuré l'environnement de travail de base, nous sommes prêts à utiliser les fonctionnalités fournies par l'API WP REST. Dans la prochaine partie de la série, nous examinerons différentes manières de configurer les méthodes d'authentification prises en charge par l'API. Ces méthodes d'authentification seront nécessaires lors de l'envoi d'une demande de récupération, de création, de mise à jour ou de suppression de contenu. Alors restez à l'écoute.
