API WP REST Récupération de données

Dans les parties précédentes de la série, nous avons examiné l'API WP REST et comment elle peut nous aider à créer de meilleures applications à l'aide du back-end WordPress..

Nous avons ensuite examiné deux manières de configurer l’authentification sur le serveur pour générer des requêtes authentifiées. La première est la méthode d’authentification de base, utile dans les environnements de développement et permettant le prototypage rapide car elle nécessite peu de temps de configuration. La deuxième méthode d'authentification est OAuth 1.0a, qui est recommandée pour les environnements de production car elle est beaucoup plus sécurisée que la méthode d'authentification de base..

Maintenant que nous avons appris comment configurer l'authentification, nous sommes prêts à générer des requêtes authentifiées pour libérer toute la puissance de l'API WP REST. Nous allons utiliser l'authentification de base tout au long de cette série pour sa facilité d'utilisation, mais il est recommandé d'utiliser l'authentification OAuth 1.0a, telle que fournie par le plug-in OAuth 1.0a, pour vos serveurs de production..

Dans la partie actuelle de la série, nous aurons notre toute première expérience pratique avec le plug-in WP REST API. Nous allons:

analyser la structure d'un OBTENIR demande
Découvrez comment le OPTIONS demander l'auto-documentation de l'API
envoyer des demandes au serveur pour la récupération de données
analyser la réponse du serveur qui inclut les propriétés, le schéma et les liens

Commençons donc par analyser la structure d'un simple OBTENIR demande.

Anatomie d'un `OBTENIR` Demande

Avant d'entrer dans les détails de la récupération de données avec l'API WP REST, nous devons nous familiariser avec la syntaxe d'une demande envoyée au serveur. Cela jettera une base solide pour nos futures interactions avec l'API WP REST..

Considérez la requête suivante envoyée au serveur:

$ GET http: // localserver / wp-json / wp / v2 / posts

Le type de demande que nous envoyons est OBTENIR-l'un des six verbes HTTP que nous avons examinés dans la première partie de cette série. UNE OBTENIR La requête est utilisée pour récupérer des données du serveur. Par conséquent, lorsqu'elle est exécutée sur le serveur, la requête ci-dessus récupère une collection de tous les objets de publication sous la forme de données JSON..

En considérant l'URI de la demande, nous pouvons le diviser en plusieurs parties:

http: // localserver /: L'URL de mon serveur de développement local. Il peut s'agir de n'importe quelle URL, en fonction de l'emplacement de votre installation WordPress..
/ wp-json: Il s'agit du préfixe de noeud final de l'API WP REST.
/ wp: L'espace de noms du plug-in WP REST API.
/ v2: C'est la version du plugin WP REST API.
/des postes: C’est la ressource que nous voulons récupérer du serveur.

L'espace de noms empêche le remplacement possible lors de l'exécution de plusieurs plug-ins, chacun fournissant sa propre couche d'abstraction pour l'API RESTful. Par conséquent, chaque abstraction fonctionne dans ses propres limites sans affecter les méthodes et les propriétés qui appartiennent à une autre abstraction..

L'espace de nom et la version n'étaient pas présents dans l'ancienne version 1.2 du plugin. Donc, dans la version précédente, la requête ci-dessus ressemblerait à ceci:

$ GET http: // localserver / wp-json / posts

Mais nous ne parlerons pas de compatibilité ascendante ici. Si vous voulez en savoir plus sur tous les changements survenus entre les versions 1.x et 2.x, vous pouvez les trouver sur la page officielle..

En plus de récupérer une collection de ressources (posts) à l'aide de l'URI ci-dessus, nous pouvons également récupérer une ressource spécifique en mentionnant son ID:

$ GET / wp / v2 / posts / 100

La requête ci-dessus renvoie un objet de publication car elle recherche une ressource de publication dont l'ID est égal à 100..

D'autres fois, nous devons également rechercher des publications qui répondent à certains critères. À cette fin, l’API WP REST fournit un moyen d’utiliser le filtre[] syntaxe:

$ GET / wp / v2 / posts? Filter [cat] = 1

En envoyant la requête ci-dessus, nous pouvons récupérer tous les articles appartenant à une catégorie d'ID 1. La syntaxe du filtre peut être particulièrement utile lors de la recherche d'articles ou de la navigation entre différentes ressources, par exemple. messages et catégories, en utilisant leurs relations.

Enfin, lorsqu’il s’agit d’arguments prenant des tableaux comme entrée dans filtre[] syntaxe, nous pouvons ajouter un ensemble vide de crochets pour exprimer des tableaux comme suit:

$ GET / wp / v2 / posts? Filter [category__and] [] = 1 & filter [category__and] [] = 2

La syntaxe ci-dessus est équivalente à la WP_Query () suivante:

 tableau (1, 2)));

Par conséquent, ce qui précède OBTENIR request récupérera une liste de publications appartenant aux deux catégories et ayant les identificateurs 1 et 2. La même syntaxe peut également être utilisée pour les arguments de tableau comportant plus de deux éléments. Veuillez noter que l'utilisation de catégorie__et paramètre nécessite une authentification de l'utilisateur avec edit_posts privilèges.

Nous allons examiner le filtre[] la syntaxe plus en détail dans une section ultérieure.

Maintenant que nous avons appris comment formater un OBTENIR demande et en fournissant ses paramètres, il est temps de jeter un oeil à la OPTIONS demande. Un OPTIONS request facilite la navigation dans l'API et constitue en fait un moyen d'auto-documentation pour rendre l'API plus accessible en documentant toutes les méthodes HTTP disponibles sur un noeud final, ainsi que les arguments qu'elles supportent..

Navigation dans l'API à l'aide de la `OPTIONS` Demande

Comme mentionné précédemment, le OPTIONS demande peut être extrêmement utile dans l'exploration de l'API. Il mentionne tous les points finaux appartenant à une route donnée et fournit une liste de paramètres pris en charge par ces points finaux pour les opérations CRUD..

Envoyons un OPTIONS demande au / wp / v2 / posts route pour vérifier quels points de terminaison il prend en charge et quels paramètres nous pouvons transmettre le long de la OBTENIR demande d'interrogation des données:

$ curl -X OPTIONS wp / v2 / posts

J'ai utilisé cURL pour envoyer la demande ci-dessus, mais vous pouvez utiliser n'importe quel outil de votre choix, y compris Postman. Assurez-vous d'inclure le chemin complet de la route ci-dessus, y compris le chemin de votre serveur..

"namespace": "wp / v2", "méthodes": […], "noeuds finaux": […], "schéma": …, "_links": …

Ce qui précède OPTIONS demande au / wp / v2 / posts route renvoie des données au format JSON contenant cinq propriétés:

espace de noms
les méthodes
points finaux
schéma
_liens

"namespace": "wp / v2",…

le espace de noms Cette propriété identifie l’espace de nom du plugin actuel. Dans notre cas c'est wp / v2, signifiant la version 2 de l'API WP REST. Nous avons déjà examiné l'espace de noms et son objectif dans la section précédente..

… "Méthodes": ["GET", "POST"],…

le les méthodes Cette propriété contient un tableau de toutes les méthodes prises en charge par l'itinéraire actuel. En regardant la réponse renvoyée par la demande ci-dessus, il est clair que le / wp / v2 / posts route prend en charge deux méthodes, à savoir OBTENIR et POSTER. Cela signifie que nous pouvons utiliser le / wp / v2 / posts route pour récupérer les messages, ainsi que la création d’un nouveau message. Nous allons traiter avec POSTER méthode dans la prochaine partie de cette série, alors concentrons-nous sur la OBTENIR méthode pour le moment.

La propriété suivante-points finaux-contient un tableau des points de terminaison pris en charge pour la route en cours. Cette propriété est directement liée à la précédente les méthodes propriété car elle répertorie les points de terminaison pour les méthodes prises en charge.

… "Noeuds finaux": ["méthodes": ["GET"], "args": …, "méthodes": ["POST"], "args": …],…

le points finaux propriété contient des valeurs d'objet qui contiennent à leur tour deux propriétés, à savoir les méthodes et args. le les méthodes propriété contient un tableau de méthodes HTTP, et la prochaine args La propriété contient tous les arguments pris en charge pour ces méthodes. Ce sont les arguments que nous envoyons avec la requête sous forme de paramètres URI.

En regardant les arguments soutenus par le OBTENIR méthode, nous rencontrons neuf arguments qui incluent le contexte, page, par page, etc. Ces objets d'argument contiennent deux propriétés, Champs obligatoires et défaut. le Champs obligatoires propriété indique si l'argument est requis et la défaut propriété représente la valeur par défaut de l'argument.

"méthodes": ["GET"], "args": "contexte": "requis": faux, "défaut": "vue", "page": "requis": faux, "défaut": 1, "per_page": "required": false, "default": 10, "filter": "required": false

le schéma propriété dans la réponse renvoyée documente toutes les propriétés de la ressource actuelle. Le schéma définit une structure pour les données au format JSON. Le format de schéma utilisé dans l'API WP REST est basé sur le brouillon 4 des spécifications de schéma JSON..

Le dernier _liens La propriété contient un tableau d'objets contenant les liens des ressources associées. La clé dans l'objet spécifie le type de relation (par exemple. auteur, collection, soi, commentaires, etc.), sa valeur étant le lien vers cette ressource associée. Cette norme de liaison est basée sur HAL (Hypertext Application Language). Pour en savoir plus sur HAL, lisez les spécifications rédigées par Mike Kelley..

De la même manière, nous pouvons envoyer un OPTIONS demande à d'autres itinéraires, y compris ceux des utilisateurs, commentaires, médias, pages, etc., de vérifier leurs méthodes et arguments pris en charge. OPTIONS les requêtes sont votre meilleur ami lorsque vous utilisez l'API WP REST.

L’API WP REST est un autre moyen d’évaluer la disponibilité de l’API en envoyant un message. OBTENIR demande au / wp-json itinéraire d'index. Ceci listera tous les itinéraires et leurs noeuds finaux avec leurs méthodes et arguments supportés.

$ curl -X GET http: // serveur wordpress / wp-json

La demande ci-dessus renverra un objet de réponse contenant une propriété routes comme suit:

Cette fonctionnalité est extrêmement puissante car elle répertorie toutes les routes, leurs méthodes et arguments pris en charge, éliminant ainsi la nécessité de toutes les documenter en externe. Nous ferons référence à cet objet de réponse lors de l'exécution d'opérations CRUD sur différentes ressources..

Après avoir examiné nos options d’exploration de l’API, commençons à travailler avec l’API WP REST pour extraire des données du serveur..

Travailler avec des postes

A présent, nous nous sommes familiarisés avec le OPTIONS request, qui constitue un moyen auto-documenté d’évaluer la disponibilité de l’API. Nous avons également examiné comment il montre les méthodes et arguments pris en charge pour une route donnée. Forts de cette connaissance, nous sommes maintenant prêts à récupérer différentes ressources du serveur à l'aide de l'API WP REST..

La ressource avec laquelle nous allons commencer est le Des postes ressource, car il est le bloc de construction principal de WordPress. Nous allons traiter de récupérer les messages en utilisant différents filtres. En appliquant ces connaissances, vous pourrez interroger les publications à l'aide de l'API WP REST comme vous le feriez avec la classe WP_Query ()..

Tout au long de cette série, nous avons travaillé avec le Des postes ressource pour illustrer les exemples de demandes et leurs réponses, et nous savons déjà comment récupérer une collecte de publications et une publication individuelle par son ID. Nous ne couvrirons donc plus cela. Au lieu de cela, nous examinerons des moyens plus avancés de récupérer des publications en utilisant les paramètres de niveau supérieur et la filtre[] syntaxe.

Travailler avec des paramètres de premier niveau

L’API WP REST expose certaines des variables de requête les plus couramment utilisées pour les publications directement sur le serveur. OBTENIR point final. Ces paramètres sont:

le contexte: La portée de la demande. Les valeurs possibles pourraient être vue, intégrer ou modifier.
page: La page actuelle de la collection d'articles.
par page: Nombre total de messages par page.
chercher: La requête de recherche. Limiter les résultats à la chaîne correspondante.
auteur: L'identifiant de l'auteur. Utilisé pour limiter les résultats appartenant à un auteur spécifique.
exclure: Un tableau d'ID de publication à exclure des résultats de recherche.
comprendre: Limiter les résultats à la publication des ID spécifiés dans ce tableau.
décalage: Décaler les résultats de la recherche d'un nombre spécifié.
ordre: L'ordre de la collection. Peut être soit asc ou desc.
commandé par: Attribut de tri de la collection. Les valeurs possibles peuvent être identifiant, Titre ou limace.
limace: Limiter les résultats à un poste ayant un slug spécifique.
statut: Utilisé pour limiter la collecte des publications ayant un statut particulier.

le le contexte Le paramètre est utilisé pour récupérer les messages en fonction de l’étendue du travail. Si nous ne faisons que répertorier les messages sur une page d’index, nous sommes prêts à utiliser le vue le contexte. Mais si nous récupérons des publications afin de les éditer, nous devons utiliser le modifier le contexte:

$ GET / wp / v2 / posts? Context = edit

le modifier paramètre de contexte introduit un supplémentaire brut domaine dans des domaines comme Titre, contenu, extrait, etc. La valeur de cette brut le champ peut être répété dans l'éditeur pour l'édition du contenu.

En utilisant le modifier contexte nécessite que vous soyez authentifié en tant qu'utilisateur avec edit_posts privilèges.

En utilisant intégrer comme la valeur de la le contexte paramètre récupère la collection des publications avec un sous-ensemble minimal de leurs propriétés.

Les autres paramètres mentionnés ci-dessus sont assez explicites et vous pouvez les utiliser dans votre client HTTP..

Ce sont les paramètres de base qui vous permettent d’interroger les publications en fonction de certains critères. Pour limiter nos capacités d’interrogation, l’API WP REST fournit la filtre[] syntaxe qui prend en charge un sous-ensemble de la WP_Query () args.

En utilisant le `filtre[]` Syntaxe

En plus de récupérer une collection d'articles en utilisant certains paramètres de base de niveau supérieur, l'API WP REST expose certaines des WP_Query () variables utilisant le filtre[] syntaxe. En utilisant cette syntaxe, nous pouvons interroger les publications de la même manière que lorsque nous travaillons avec WP_Query () classe.

Les paramètres de pagination sont les plus importants de tous les filtres, car ils sont largement utilisés sur les pages de liste de publication. Les paramètres de pagination nous permettent d'afficher un nombre spécifique de publications par page et de naviguer vers un nombre spécifique de pages contenant des publications..

Par défaut, un OBTENIR request récupère une collection de 10 articles par page. Voyons comment nous pouvons soumettre un OBTENIR demande de ne récupérer que cinq articles par page:

$ GET / wp / v2 / posts? Filter [posts_per_page] = 5

La demande ci-dessus utilise le posts_per_page variable que vous connaissez peut-être si vous avez travaillé avec WP_Query ().

le paginé paramètre est utilisé en conjonction avec le posts_per_page paramètre, et il est utilisé pour naviguer vers un nombre spécifique de pages. Après avoir récupéré cinq articles par page, nous ferions la demande suivante pour accéder à la deuxième page:

$ GET / wp / v2 / posts? Filter [posts_per_page] = 5 & filter [paged] = 2

le posts_per_page et paginé les filtres peuvent être extrêmement pratiques lorsque vous travaillez à construire une pagination sur des pages de liste à l'aide de l'API WP REST. Ces deux paramètres sont équivalents à la par page et page paramètres de niveau supérieur. Par conséquent, la requête suivante effectue le même travail que la précédente:

$ GET / wp / v2 / posts? Per_page = 5 & page = 2

En plus de la collection de publications renvoyées par la requête ci-dessus, le serveur renvoie également un certain nombre d'en-têtes avec une réponse contenant des informations utiles, notamment le nombre total de publications et le nombre de pages. Ces valeurs sont contenues dans le X-WP-TotalPages et X-WP-Total en-têtes de réponse.

le X-WP-TotalPages et X-WP-Total Les en-têtes de réponse sont extrêmement utiles lors de la création d'une pagination à l'aide de l'API WP REST, car ils indiquent respectivement le nombre total de pages et le nombre total de publications..

Outre les filtres de pagination, l’autre utilisation la plus importante de la filtre[] La syntaxe consiste à pouvoir interroger les publications par leur date. À cette fin, le filtre[] La syntaxe prend en charge huit paramètres, les mêmes que ceux du WP_Query () classe:

année: L'année à quatre chiffres (par exemple 2015 ou 2016)
Monthnum: Le numéro du mois de 1 à 12
m: Six chiffres année-mois (par exemple 201601)
w: La semaine de l'année de 0 à 53
journée: Le jour du mois du 1 au 31
heure: L'heure du jour de 0 à 23
minute: La minute de l'heure de 0 à 60
seconde: La seconde de la minute de 0 à 60

Donc, si nous recherchons les articles publiés à la date du 15/10/2015 (aaaa / mm / jj), vous pouvez le faire avec la requête suivante:

$ GET / wp / v2 / posts? Filtre [année] = 2015 & filtre [monthnum] = 10 & filtre [jour] = 15

Une requête similaire peut être préparée à l'aide des paramètres ci-dessus si nous devons affiner notre recherche à l'heure et à la minute exactes..

Nous avons déjà vu dans une section précédente de ce didacticiel comment récupérer des publications appartenant à une catégorie spécifique ou à plusieurs catégories à l'aide de l'outil filtre [chat] et filtrer [catégorie__et] paramètres. Maintenant, nous allons utiliser le filtre [catégorie__in] paramètre pour afficher les messages appartenant aux catégories ayant un identifiant de 5 et 6:

$ GET / wp / v2 / posts? Filter [category__in] [] = 5 & filter [category__in] [] = 6

La demande ci-dessus récupérera une liste de tous les postes appartenant aux catégories ayant un identifiant de 5 et 6.

L’effet inverse pourrait être obtenu en utilisant le filtre [catégorie__not_in] paramètre de la manière suivante:

$ GET / wp / v2 / posts? Filter [category__not_in] [] = 5 & filter [category__not_in] [] = 6

Cela permettra de récupérer une liste de postes en excluant tous les postes appartenant à des catégories ayant un identifiant de 5 ou 6..

Plus pourrait être écrit sur l'aide de la filtre[] syntaxe, mais je ne couvrirai pas tout cela ici. Vous pouvez trouver une liste de toutes les variables de requête supportées par le filtre[] syntaxe dans la documentation officielle de la version 1 du plugin. Une grande partie de ces informations est toujours valide avec la version 2 de l'API WP REST, mais elle manque toujours dans certains domaines. Au moment de la rédaction de ce tutoriel, la documentation officielle de la version 2 ne dit rien sur le filtre[] syntaxe et les vars de requête qu’il supporte, mais nous pouvons espérer voir des améliorations dans la documentation officielle dans un proche avenir car plusieurs personnes (dont moi-même) contribuent au développement et à la documentation du plugin.

Maintenant que nous avons examiné différentes options pour interroger des publications à l'aide de l'API WP REST, nous sommes prêts à poursuivre notre route et à examiner d'autres ressources prises en charge par l'API WP REST..

Utilisation de révisions de publication, de catégories, de balises et de méta

Les révisions de publication permettent de visualiser et de restaurer les modifications apportées à une publication. L’API REST WP permet de visualiser toutes les révisions d’une publication en interrogeant le /des postes// révisions point final. Ainsi, pour une publication ayant un identifiant de 10, toutes les révisions peuvent être récupérées en envoyant la requête suivante:

$ GET / wp / v2 / posts / 10 / révisions

La requête ci-dessus renverra un tableau contenant des objets de révision. L'objet révisions contient un sous-ensemble de propriétés trouvées dans l'objet post. Vous trouverez ci-dessous un exemple d'objet de révision dans Postman:

Une révision spécifique peut être récupérée étant donné que nous connaissons son identifiant. Donc, une révision ayant un ID de 2 et post ayant un ID de 10 peut être récupérée par l'objet suivant:

$ GET / wp / v2 / posts / 10 / révisions / 2

La demande ci-dessus renverra un seul objet de révision.

Outre les révisions de publication, les catégories d'une publication spécifique peuvent être récupérées à l'aide de la requête suivante:

$ GET / wp / v2 / categories? Post =

Et pour les tags, nous utilisons la requête suivante:

$ GET / wp / v2 / tags? Post =

Avec être l'ID de la poste.

Si nous devons extraire post meta pour les envois ayant un ID de 10, nous envoyons la requête suivante en tant qu'utilisateur authentifié:

$ GET / wp / v2 / posts / 10 / meta

Cela retournera un tableau de méta-objets.

Veuillez noter que pour utiliser les méta de page et de page dans l'API WP REST, le plug-in compagnon doit être installé sur GitHub par l'équipe API REST WP..

Travailler avec d'autres ressources

Nous avons maintenant acquis une base assez solide pour travailler avec l'API WP REST afin de récupérer des données. Nous avons déjà examiné la demande d'options et la manière dont elle nous aide à explorer l'API sans recourir à une documentation externe..

Vous pouvez toujours envoyer un OPTIONS demander à une ressource particulière et vérifier quels points de terminaison et paramètres sont pris en charge. Si vous devez répertorier toutes les routes fournies par l’API WP REST, vous pouvez envoyer un message. OBTENIR demande au noeud final d'index à / wp-json comme nous avons appris à le faire au début de ce tutoriel.

Compte tenu de cet avantage de l'auto-documentation, je ne pense pas que nous ayons besoin d'explorer davantage chaque ressource individuelle dans ce didacticiel, car vous pouvez maintenant le faire vous-même..

Quoi de neuf ensuite?

Dans ce long didacticiel, nous avons appris à explorer l'API à l'aide de la requête OPTIONS et à extraire des données du serveur à l'aide de l'API WP REST. Nous venons d'examiner une poignée de ressources, notamment des publications, une révision et une méta, car nous ne pouvions pas couvrir toutes les ressources prises en charge dans un seul tutoriel. Mais vous devriez maintenant être capable d'explorer l'API vous-même en utilisant les techniques que nous avons apprises dans ce tutoriel..

WordPress a une économie incroyablement active. Il existe des thèmes, des plugins, des bibliothèques et de nombreux autres produits qui vous aident à construire votre site et votre projet. La nature open source de la plate-forme en fait également une excellente option à partir de laquelle vous pouvez améliorer vos compétences en programmation. Quel que soit le cas, vous pouvez voir tout ce que nous avons disponible sur le marché Envato..

Dans le prochain épisode de cette série, nous allons apprendre à effectuer les trois autres opérations de CRUD, à savoir créer, mettre à jour et supprimer des ressources. Alors restez à l'écoute…

Code