Dans cet article, je vais essayer de créer un aperçu de la façon de créer des points de terminaison d’API REST personnalisés et d’effectuer des demandes pour eux dans un bloc Gutenberg personnalisé. C’est-à-dire, faire des demandes avec des fetchméthodes d’informations non disponibles dans les magasins de données enregistrés de WordPress.
Un rappel amical : la plupart des informations de base sont déjà disponibles dans les magasins de données de WordPress. Par exemple, les requêtes de base sur les publications, les pages, les types de publication personnalisés, les taxonomies, les auteurs, les médias, etc. sont disponibles telles quelles sans avoir à créer vos propres points de terminaison personnalisés. Pour accéder à ces magasins, vous préférez utiliser le module de données de base de WordPress (withSelectet select()). Vous trouverez ci-dessous une partie du didacticiel qui explique en profondeur comment procéder.
API REST WordPress
Si vous ne le saviez pas déjà; WordPress REST API est une interface JSON pour envoyer et recevoir des données de votre site WordPress. Il peut être utilisé en externe ou en interne. Avec l’éditeur Gutenberg et le passage à Javascript, les utilisations de l’API REST ont définitivement augmenté. L’API REST WordPress a tout un tas de points de terminaison que nous pouvons utiliser. Consultez une référence complète sur tous les points de terminaison de l’API REST ici. Vous trouverez par exemple des points de terminaison pour les publications et la plupart des autres contenus internes, à la fois pour la lecture et la mise à jour. Les développeurs de thèmes ou de plugins peuvent enregistrer leurs propres points de terminaison personnalisés.
Votre site WordPress a une URL d’API REST racine, par défaut située à <your domain>/wp-json. Par exemple, un WordPress local avec l’URL http://localhost/wordpress/peut accéder à l’API REST à l’adresse http://localhost/wordpress/wp-json. À partir de là, nous devons ajouter des points de terminaison. En se référant à la référence ci-dessus des points de terminaison, nous pouvons récupérer une liste des derniers messages dans le point de terminaison /wp/v2/posts. Cela signifie que si vous accédez à http://localhost/wordpress/wp-json/wp/v2/postsvotre navigateur, vous obtiendrez une réponse au format JSON des derniers messages de votre site WordPress.
Une note sur les espaces de noms s’impose. Une URL d’API REST commence par un espace de noms (‘ wp/v2‘ est l’espace de noms de WordPress, comme indiqué dans les exemples d’URL ci-dessus). Les espaces de noms sont un concept permettant d’éviter les conflits dans le cœur de WordPress, les thèmes et les plugins ajoutant des points de terminaison portant le même nom. Créez votre propre espace de noms unique – généralement une forme slug de votre nom de thème ou de plugin. Après le slug, une règle générale consiste à ajouter le numéro de version, commençant normalement à v1. Par exemple, le slug de mon thème est ‘ awhitepixel‘, donc si je devais créer des points de terminaison personnalisés dans mon thème, j’utiliserais l’espace de noms ‘ awhitepixel/v1‘. Avec cet espace de noms, je pourrais enregistrer un point de terminaison ‘ posts‘ et cela ne poserait aucun problème même s’il est identique au nom du point de terminaison de WordPress.
Travailler avec l’API REST dans WordPress est un vaste sujet avec beaucoup de bonnes informations disponibles. Dans cet article, je me concentre sur la convivialité dans l’éditeur Gutenberg et sur la façon de les récupérer en Javascript.
Ce que nous ferons, et ce dont nous avons besoin
La facilité d’utilisation pour demander des informations personnalisées a un large éventail de cas d’utilisation, vous devrez donc généralement personnaliser les exemples de code ci-dessous pour répondre à vos besoins. Les données peuvent être une requête de publication personnalisée, une requête SQL personnalisée ou quelque chose de complètement différent.
Lorsque nous créons un point de terminaison personnalisé, nous contrôlons totalement son retour. Nous pouvons effectuer tout type d’opérations et de requêtes dans WordPress/PHP et les transmettre au format JSON. Et dans notre bloc Gutenberg, nous pourrons récupérer ce retour et en faire ce que nous voulons dans la editfonction du bloc. En règle générale, vous utiliserez les données pour présenter à l’utilisateur final un choix ou des informations dans l’éditeur de blocs, mais vous pouvez également stocker des informations dans votre bloc pour une utilisation ultérieure. Vous pouvez également créer vos propres magasins personnalisés pour ces données, mais je n’expliquerai pas comment procéder.
Je suppose que vous savez déjà comment créer des blocs Gutenberg personnalisés, je ne vais donc pas détailler cela ici.
Création d’un point de terminaison d’API REST
L’enregistrement d’un point de terminaison d’API REST personnalisé se fait en PHP. Vous ajouteriez ce code dans votre thème functions.phpou dans un code de plugin actif. Accrochez une fonction à l’ action rest_api_initet exécutez la fonction [register_rest_route](https://developer.wordpress.org/reference/functions/register_rest_route/)()pour chaque point de terminaison que vous souhaitez enregistrer.
Fournissez votre espace de noms comme premier paramètre, votre itinéraire de point de terminaison comme deuxième et un tableau de paramètres comme troisième paramètre à register_rest_route(). Le quatrième paramètre contrôle si vous souhaitez ou non remplacer une route existante ; pas quelque chose que nous allons regarder ici. Dans le tableau du troisième paramètre, vous devez au minimum définir la propriété ‘ callback‘ sur une fonction chargée de renvoyer les données du point de terminaison. La définition de ‘ method‘ est également courante, par exemple, la définition de votre point de terminaison sur ‘ GET‘, ‘ POST‘, ‘ PUT‘, etc.
Commençons par enregistrer un point de terminaison simple ;
L’espace de noms de mon thème est ‘ awhitepixel/v1‘ et j’enregistre un point de terminaison ‘ mydata‘ dans cet espace de noms. Cela signifie que je peux accéder à mon API REST personnalisée sur http://localhost/wordpress/wp-json/awhitepixel/v1/mydata.
Lors de l’enregistrement (ou de la modification) des routes de l’API REST, vous devrez vider vos permaliens pour que cela fonctionne. Vous pouvez le faire en visitant Paramètres> Permaliens et cliquez simplement sur Enregistrer.
Le code ci-dessus ne fonctionne pas encore, car je n’ai pas défini la fonction définie comme rappel : awhitepixel_rest_route_mydata. La fonction de rappel reçoit un paramètre ; un tableau de données avec des informations et des arguments transmis à partir de la requête. Enfin, vous devez examiner attentivement le retour de votre fonction de rappel.
Tout d’abord, vous devez toujours renvoyer quelque chose à partir de votre rappel de point de terminaison. Tout retour sera automatiquement converti en JSON par WordPress. Cela signifie que vous pouvez renvoyer pratiquement n’importe quelle forme de données dans votre fonction ; une chaîne, null, un tableau ou une [WP_Error](https://developer.wordpress.org/reference/classes/wp_error/)instance. Vous pouvez également choisir de renvoyer un [WP_REST_Response](https://developer.wordpress.org/reference/classes/wp_rest_response/)objet pour plus de contrôle, par exemple sur le code d’état ou les informations d’en-tête. Je recommande d’envelopper le retour dans la fonction [rest_ensure_response](https://developer.wordpress.org/reference/functions/rest_ensure_response/)()pour vous assurer que votre réponse est une réponse REST valide.
Définissons notre fonction de rappel et renvoyons une chaîne simple comme début ;
function awhitepixel_rest_route_mydata($data) {
$response = 'Hello there!';
return rest_ensure_response($response);
}Avec le code ci-dessus (et les permaliens vidés), je peux maintenant accéder à l’URL http://localhost/wordpress/wp-json/awhitepixel/v1/mydata.
À partir de là, nous pouvons ajouter n’importe quel type de code dans notre fonction de rappel pour générer les données appropriées à renvoyer. Vous pouvez interroger le contenu WordPress avec par exemple [WP_Query](https://developer.wordpress.org/reference/classes/wp_query/), effectuer des requêtes dans la base de données ou demander des données externes. Cette partie dépend de vous.
Maintenant, passons du côté opposé ; comment faire les demandes.
Faire des requêtes API REST en Javascript
L’exécution d’une requête REST est généralement effectuée à l’aide [fetch](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API)de Javascript. WordPress fournit son propre wrapper fetchqui simplifie les requêtes de l’API WordPress REST ; [wp.apiFetch](https://developer.wordpress.org/block-editor/packages/packages-api-fetch/). C’est ce que je vais utiliser dans mon bloc Gutenberg personnalisé. Gardez à l’esprit que les fetchrequêtes renvoient une "promesse" – nous devons donc enchaîner a .then()afin de gérer le retour réel de la requête. L’utilisation de base ressemble à ceci ;
apiFetchnous permet de fournir une pathpropriété au lieu de construire l’URL complète. Tout ce que nous devons fournir est l’espace de noms et le point de terminaison, et apiFetchnous les ajouterons à l’URL racine de l’API REST de WordPress. Dans la .then()fonction, nous avons accès aux données déjà converties en JSON. C’est ici que vous feriez quelque chose avec les données. Habituellement, vous stockez les données renvoyées, par exemple dans l’état du composant.
Vous trouverez ci-dessous un exemple de composant de bloc Gutenberg personnalisé edit. Il est basé sur les classes afin d’être utilisé statepour stocker les données renvoyées par la demande d’API REST. Cela nous permet également d’exécuter la requête componentDidMount()lors de son premier montage (voir la documentation de React sur les méthodes de cycle de vie ). Tout cela fournit un exemple simple pour que vous compreniez le concept de base ; pas comme une recette pour le faire exactement comme ça. Vous pouvez envisager d’utiliser des crochets React et des composants fonctionnels ou de construire un composant d’ordre supérieur à la place.
L’exemple ci-dessus est un composant basé sur une classe qui est fourni à la editfonction du bloc dans registerBlockType(). Il configure un objet d’état d’un tableau pour contenir les données (cela dépend des données que vous renvoyez, évidemment), et un booléen d’état pour savoir quand la requête asynchrone est retournée. Une fois que le composant est monté (rendu pour la première fois), il exécute la fonction pour effectuer la apiFetchrequête. Nous définissons le chemin vers le point de terminaison que nous avons enregistré en PHP ci-dessus. La méthode est GET par défaut, nous n’avons donc pas besoin de le spécifier dans apiFetch. Et à l’intérieur .then()de la fonction lorsque la requête est prête, nous mettons à jour l’état du composant avec les données renvoyées.
De toute évidence, la fonction de rendu de votre bloc ferait plus avec les données renvoyées elles-mêmes. Vous voudrez peut-être fournir les données à l’utilisateur en présentant d’une manière ou d’une autre une liste parmi laquelle choisir. Tout dépend du type de données dont il s’agit et de l’utilisation que vous souhaitez en faire.
Passer des arguments au point de terminaison
Dans certains cas, nous devons transmettre certains arguments au point de terminaison. Les utilisations courantes consistent à transmettre un ID après le point de terminaison ; par exemple http://localhost/wordpress/wp-json/wp/v2/posts/14renverrait l’ID de poste 14.
C’est assez simple et se fait en ajoutant un modèle de recherche regex au point de terminaison lors de son enregistrement. Cela nécessite une certaine connaissance des expressions régulières pour créer des modèles complexes, mais ci-dessous se trouve un exemple qui correspond à un nombre et lui attribue le nom "id". Nommer les correspondances nous donne les moyens d’accéder à la variable dans notre fonction de rappel. Laissez-moi vous montrer ce que je veux dire.
Enregistrons une nouvelle route de point de terminaison. Nous utilisons le même point de terminaison que précédemment (‘ awhitepixel/v1/mydata‘) mais pour cette route, nous ajoutons une correspondance regex pour un nombre à la fin.
Le modèle regex (?P<id>[d]+)semble cryptique, mais sera assez clair avec une compréhension de base de regex. La [d]+partie correspond à n’importe quel nombre (0-9) 1 ou plusieurs fois. Les parties (?P<id>et )correspondent à un groupe nommé. Le nom du groupe est dans ce cas id, mais vous pouvez nommer votre ou vos groupes comme vous le souhaitez.
Vous pouvez choisir de diriger ce point de terminaison vers une fonction de rappel distincte, mais j’ai choisi d’utiliser la même fonction pour gérer les requêtes /mydataet. /mydata/<ID>Cela signifie que je peux dans ma fonction de rappel faire :
function awhitepixel_rest_route_mydata($data) {
if ($data['id']) {
$response = 'Create return for ID: '. $data['id'];
} else {
$response = 'Create general return (no ID provided)';
}
return rest_ensure_response($response);
}N’oubliez pas que le paramètre de la fonction de rappel contient les arguments renvoyés. Parce que j’ai nommé mon groupe correspondant ‘ id‘, la valeur correspondante sera accessible dans $data['id']. Et enfin parce que j’utilise la même fonction pour gérer les requêtes avec et sans ID, je peux facilement basculer entre les deux retours différents.
Avec ceci (et des permaliens actualisés), j’obtiendrai ces réponses pour mes points de terminaison personnalisés :
