Guide détaillé sur la création et la récupération de points de terminaison d’API REST WP personnalisés

Cet article montrera comment créer des points de terminaison WordPress REST personnalisés et différentes méthodes pour leur envoyer des requêtes. Il y aura des exemples en PHP, jQuery et Javascript vanille.

Je suppose que vous connaissez déjà l’API WP REST, mais voici un bref résumé. WordPress REST API est une interface JSON pour envoyer et recevoir des données de votre site WordPress. Vous pouvez accéder aux points de terminaison (chemins/URL spécifiques) à la fois en externe et en interne. WordPress a déjà un tas de points de terminaison disponibles, par exemple pour récupérer des publications, des catégories, rechercher sur le site et plus encore. Voir un aperçu des points de terminaison WordPress par défaut ici. Mais les développeurs sont entièrement libres de créer leurs propres points de terminaison personnalisés à l’aide de cette API, pour effectuer des actions ou récupérer des données.

Nous allons commencer par la première étape ; qui crée des points de terminaison personnalisés. Si vous êtes seulement intéressé par la façon de faire des demandes, passez directement à la deuxième partie.

Créer des points de terminaison personnalisés

L’enregistrement des points de terminaison personnalisés se fait en PHP. Vous pouvez ajouter le code au fichier de code de votre thème functions.phpou d’un plugin actif. Créez une fonction accrochée à rest_api_initet utilisez la fonction [register_rest_route](https://developer.wordpress.org/reference/functions/register_rest_route/)()pour chaque point de terminaison que vous souhaitez ajouter.

En tant que premier paramètre, register_rest_route()vous devez fournir un espace de noms unique pour vous assurer que vos points de terminaison n’entrent pas en conflit avec les autres. Utilisez le slug de votre thème ou plugin. Il est courant d’inclure ensuite un /suivi d’un numéro de version pour votre code. À titre d’exemple, j’utiliserai l’espace de noms awhitepixel/v1. Le deuxième paramètre est le chemin (qui suit l’espace de noms). Enfin, vous pouvez éventuellement fournir un tableau comme troisième paramètre avec des options. Dans ce tableau, vous pouvez par exemple définir la méthode de requête (GET, POST ou toute autre), définir des paramètres et, surtout, définir la fonction à exécuter lorsque ce point de terminaison est demandé.

Au minimum, vous devez fournir les arguments ‘method’ et ‘callback’ (qui est la fonction pour gérer les données du point de terminaison) comme troisième paramètre. Pour ‘méthode’, vous pouvez les définir comme ‘ GET', 'POST', 'PUT', ou toute autre méthode de requête valide (ou un tableau de plusieurs), mais je recommande d’utiliser les valeurs par défaut de WordPress pour cela. Ils sont les suivants :

• WP_REST_Server::READABLE méthode ‘ GET‘
• WP_REST_Server::EDITABLE méthodes ‘ POST‘, ‘ PUT‘ et ‘ PATCH‘
• WP_REST_Server::DELETABLE méthode ‘ DELETE‘
• WP_REST_Server::ALLMETHODS toutes les méthodes ci-dessus

Créons un point de terminaison personnalisé de base qui peut être atteint à l’aide de requêtes GET :

À la ligne, #2nous avons défini notre point de terminaison personnalisé comme ‘ awhitepixel/v1/getsomedata‘. L’URL complète serait l’URL racine de l’API REST de WordPress préfixée, qui est <yourdomain>/wp-json. Ainsi, l’URL complète du point de terminaison ci-dessus serait ‘ <yourdomain>/wp-json/awhitepixel/v1/getsomedata‘. À la ligne, #4nous avons fourni un nom de fonction comme rappel, que nous ajouterons sous peu.

Lors de l’enregistrement (ou de la modification) des routes de l’API REST à l’aide register_rest_route()de, vous devrez vider vos permaliens pour que cela fonctionne. Vous pouvez le faire en visitant Paramètres> Permaliens dans l’administrateur et cliquez simplement sur Enregistrer.

Nous n’avons pas encore défini la fonction de rappel – qui est la fonction du code qui gère la réaction de l’utilisation de ce point de terminaison. Il doit renvoyer une réponse valide REST (en JSON), vous devrez donc renvoyer quelque chose même si le point de terminaison n’est pas censé renvoyer de données. Vous pouvez utiliser la fonction [rest_ensure_response](https://developer.wordpress.org/reference/functions/rest_ensure_response/)()function ou créer une instance d’ WP_REST_Responseobject comme retour du rappel. En tant que paramètre de la fonction de rappel, nous obtenons un WP_REST_Requestobjet qui contient toutes les informations sur la requête, y compris tous les paramètres. Créons une fonction de rappel simple qui envoie simplement du texte en réponse :

function awhitepixel_rest_route_getsomedata( $request) {
    $response = 'Hello there!';
    return rest_ensure_response( $response );
}

C’est la manière la plus basique d’écrire un callback. La fonction rest_ensure_response()s’assure que toutes les données que nous fournissons (la chaîne) sont converties en une réponse valide REST. Évidemment, vous voudrez ajouter plus de code ici, soit pour faire quelque chose dans WordPress, soit pour récupérer et renvoyer des données.

Avec le code ci-dessus (enregistrement du point de terminaison et de la fonction de rappel), vous pouvez essayer d’accéder à l’URL de votre navigateur et voir ce que vous obtenez. (Pensez à vider vos permaliens). Aller à <domain>/wp-json/awhitepixel/v1/getsomedatadans le navigateur affichera la chaîne "Hello there!".

Acceptation des paramètres

Il est très courant et utile d’autoriser les points de terminaison à accepter des paramètres. Par exemple, si votre site contient par exemple des données sur les produits, vous voudriez un point de terminaison où vous pouvez fournir un ID de produit afin d’obtenir les données de ce produit. Il y a deux façons de procéder. La méthode la plus courante consiste à utiliser la chaîne de requête GET (qui est ajoutée après l’URL après un ?, séparée par &au format clé=valeur. Par exemple ‘ <endpoint>/product/?product_id=14‘). Vous pouvez également définir un modèle d’URL "plus joli", où les paramètres font partie du chemin. Par exemple ‘ <endpoint>/product/14/‘. Cette dernière méthode nécessite cependant une certaine connaissance des regexes. La méthode que vous choisirez dépend de vous, je vais vous montrer les deux ci-dessous.

Paramètres GET

La définition des paramètres GET possibles sur votre point de terminaison utilise la argsclé ‘ ‘ dans register_rest_route()le troisième paramètre de. Pour chaque paramètre que vous souhaitez autoriser, définissez la valeur de clé (dans l’exemple ci-dessus ‘ product_id‘) et un tableau d’options pour ce paramètre. En tant qu’options, vous pouvez définir le format du paramètre (s’il attend par exemple un nombre ou une chaîne) et également décider si ce paramètre est requis ou non.

Par exemple, nous voulons permettre à notre point de terminaison d’accepter ‘ product_id‘ comme nombre non requis.

Si vous définissez un paramètre comme vrai dans required, WordPress se chargera de renvoyer une réponse d’erreur 400. De même si vous passez un format invalide, par exemple "hello" comme valeur à un paramètre qui attend un nombre.

À la ligne #15de la fonction de rappel, vous voyez comment obtenir la valeur du paramètre à partir de la requête ; en utilisant la méthode get_param()dans l’objet passé WP_REST_Request. À titre d’exemple, je montrerai différentes réponses selon qu’elles product_idont été fournies ou non (rappelez-vous que nous l’avons défini comme facultatif). La logique de modification de votre code en fonction des paramètres fournis dépend entièrement de vous et de votre projet. Vous pouvez avoir moins de points de terminaison qui acceptent un grand nombre de paramètres, ou beaucoup plus de points de terminaison distincts pour chaque cas spécifique.

Avec le code ci-dessus, j’obtiendrai "Hello there!" lorsque je visite <yourdomain>/awhitepixel/v1/getsomedataet "Return product data for ID 14" lorsque je vais sur <yourdomain>/awhitepixel/v1/getsomedata/?product_id=14.

Paramètres dans le cadre du chemin

Si vous souhaitez autoriser les paramètres à faire partie du chemin plutôt que la chaîne de requête GET, vous pouvez le faire. Vous fournirez ensuite un modèle regex dans le chemin – le deuxième paramètre de register_rest_route().

La création de modèles regex peut sembler assez énigmatique, mais comme il s’agit d’un sujet complet, vous trouverez facilement des exemples pour des cas spécifiques si vous le recherchez sur Google. Je vais montrer un exemple de définition d’une expression régulière qui accepte un nombre de n’importe quelle longueur ;

Comme vous pouvez le voir à la ligne 2, j’ai ajouté le motif regex (?P<product_id>[d]+)à la fin. Ce modèle signifie que nous devons collecter un nombre (d) de n’importe quelle longueur (+) et affecter la valeur collectée dans la clé de paramètre product_id. Et dans notre fonction de rappel, nous utilisons exactement la même méthode que lors de la configuration des paramètres GET ; get_param()dans l’ WP_REST_Requestobjet fourni à la fonction.

Avec le code ci-dessus (après avoir vidé les permaliens), nous pouvons visiter l’URL <yourdomain>/wp-json/awhitepixel/v1/getsomedata/14pour obtenir notre réponse. Cette méthode donne certainement des URL "plus jolies", mais le code peut facilement devenir plus difficile à lire et à corriger. Quelle que soit la méthode que vous choisissez, c’est à vous de décider.

Renvoyer la bonne réponse

Plus tôt, j’ai brièvement mentionné comment la fonction de rappel doit renvoyer une réponse REST appropriée. Jusqu’à présent, nous avons utilisé le plus simple rest_ensure_response(). Mais parfois, vous souhaiterez peut-être plus de contrôle sur le retour de votre point de terminaison. Vous pouvez par exemple vouloir contrôler le code d’état de la réponse HTTP. Supposons que vous créez un point de terminaison où vous pouvez fournir un ID de produit et obtenir des données pour ce produit. Mais si cet ID de produit n’existe pas, ou si d’autres paramètres prêtent à confusion, vous souhaiterez peut-être renvoyer un code d’état, par exemple 400 (Bad request) ou 404 (Not found). Ou peut-être 500 (erreur de serveur). Toujours passer 200 (succès) même si la demande était mauvaise peut causer des problèmes du côté de l’expéditeur.

Je recommanderais alors votre fonction de rappel renvoyant un WP_REST_Responseobjet. Avec cet objet, vous pouvez contrôler plusieurs choses, y compris le code d’état. C’est plus facile que vous ne le pensez! Dans la forme la plus simple, vous créeriez une nouvelle instance de WP_REST_Response, fourniriez un tableau des données à renvoyer comme premier paramètre et le code d’état comme deuxième paramètre. Par exemple:

Dans l’exemple ci-dessus, nous stockons le retour de la awhitepixel_get_product()fonction dans une variable. Cette fonction n’existe pas, et vous devriez la remplacer par la fonction qui devrait récupérer (ou faire) les actions que vous voulez dans votre projet. Mais disons que la fonction renvoie un tableau vide et cela signifie que quelque chose s’est mal passé (par exemple, le produit n’existait pas). Nous pourrions alors renvoyer un WP_REST_Responseobjet avec le code d’état 400, et éventuellement un message sous forme de données expliquant pourquoi il a échoué (ligne #5-9). Sinon, nous renvoyons les données avec le code de statut 200 Success (ligne #10).

Envoi de requêtes à des points de terminaison (personnalisés)

Passons à l’autre côté, la partie envoi : comment envoyer des requêtes à nos points de terminaison personnalisés. Normalement, vous enverriez des demandes d’API WP REST en utilisant Javascript et vous trouverez ici des exemples d’utilisation de jQuery, de la bibliothèque WordPress et de Javascript vanilla. Il est rare, mais possible, d’effectuer également une requête REST avec PHP – j’en ai donc également inclus un exemple.

La première chose à savoir est que vous devez évidemment connaître l’URL complète pour envoyer une demande. Je ne recommande pas de coder en dur le domaine (avant le point de terminaison) car il existe plusieurs façons de l’obtenir si votre Javascript fonctionne dans WordPress. Dans les anciennes versions de WordPress, vous deviez utiliser [wp_localize_script](https://developer.wordpress.org/reference/functions/wp_localize_script/)()PHP et transmettre l’URL REST principale en tant que variable Javascript globale. Mais les exemples ci-dessous montrent une nouvelle et meilleure façon d’obtenir l’URL racine REST du site WordPress.

Une autre chose à noter est que pour votre projet, vous envelopperiez probablement les demandes à la suite d’une action. Pour garder les choses simples, je prépare toutes les demandes au DOM, vous devez donc vous assurer d’envelopper le code de la demande, par exemple à la suite d’un clic d’un visiteur sur un bouton.

Utilisation de jQuery

Si vous possédez et souhaitez utiliser la bibliothèque jQuery, vous pouvez utiliser sa [$.ajax](https://api.jquery.com/jquery.ajax/)()fonction.

Mais d’abord une note sur les dépendances de votre fichier Javascript. De toute évidence, votre script aurait besoin 'jquery'd’une dépendance pour le mettre en file d’attente. Mais pour accéder facilement à l’URL racine REST de votre WordPress, ajoutez une autre dépendance ; ‘wp-api-demande’. Cela garantit que la variable Javascript wpApiSettings.rootest disponible et contient l’URL racine de l’API REST. Voici un exemple de la façon dont vous mettriez votre script en file d’attente pour illustrer cette dépendance ;

add_action( 'wp_enqueue_scripts', function() {
    wp_enqueue_script(
        'awp-javascript-wp-rest', 
        get_stylesheet_directory_uri(). '/assets/js/javascript_wp_rest.js', 
        [ 'jquery', 'wp-api-request' ], 
        null, 
        true
    );
} );

Line #5est la plus intéressante; où nous définissons à la fois jQuery et wp-api-requestcomme dépendance. Ensuite, dans notre fichier Javascript, nous pouvons effectuer une requête API REST WP comme suit :

( function( $) {
    // Send request
    $.ajax( {
        url: wpApiSettings.root + 'awhitepixel/v1/getsomedata',
        method: 'GET',
        data: {
            product_id: 14
        },
        success: function( data) {
            console.log( data );
        }
    } );
} )( jQuery );

C’est aussi basique que possible. Nous utilisons $.ajax()pour envoyer une requête GET à l’url définie. En tant qu’URL, nous utilisons wpApiSettings.rootpour obtenir l’URL racine de l’API REST, puis nous ajoutons le point de terminaison souhaité après celle-ci ; dans notre cas, le point de terminaison personnalisé que nous avons créé précédemment. En option, nous pouvons passer des paramètres dans ‘data’. L’exemple ci-dessus passe product_idavec la valeur 14 au point de terminaison. Enfin, dans la successfonction, nous recevons la demande (réussie) en tant que paramètre et nous sommes libres d’en faire ce que nous voulons. Dans l’exemple ci-dessus, nous l’imprimons simplement sur la console.

Utilisation de la bibliothèque WordPress (non-jQuery)

Si votre site WordPress n’a pas ou ne peut pas utiliser la bibliothèque jQuery, vous pouvez utiliser la bibliothèque Javascript de WordPress pour effectuer facilement une requête API REST. La fonction est disponible dans l’espace de noms apiFetchglobal de WordPress. est une méthode wrapper pour la fonction standard du navigateur (qui est démontrée ensuite).wp``wp.apiFetch()``fetch()

Notre Javascript aura besoin de la dépendance ‘wp-api’ pour utiliser wp.apiFetch(). Par exemple, nous pourrions mettre le script en file d’attente comme ceci :

add_action( 'wp_enqueue_scripts', function() {
    wp_enqueue_script(
        'javascript-wp-rest', 
        get_stylesheet_directory_uri(). '/assets/js/javascript_wp_rest.js', 
        [ 'wp-api' ], 
        null, 
        true
    );
} );

Vous trouverez la dépendance critique à la ligne #5. Avec cela, nous nous sommes assurés que notre fichier Javascript est wp.apiFetch()disponible. Voici un exemple basique d’utilisation :

Gardez à l’esprit que la ligne #9-13n’est qu’une logique pour exécuter la fonction une fois que DOM est prêt.

L’un des avantages de l’utilisation par wp.apiFetch()rapport à la normale fetch()est que nous pouvons utiliser ‘path’ qui ne nécessite que le point de terminaison, au lieu de ‘url’ qui nécessite l’URL complète. Un autre avantage est que la première "chaîne" de .then()renvoie les données déjà formatées en JSON. Lorsque vous utilisez l’original .fetch(), vous avez besoin de plus de chaînes ".then()". Jetez un œil à l’exemple suivant ("Utiliser du Javascript vanille") pour voir ce que je veux dire.

Gardez à l’esprit que fetch()(et par conséquent wp.apiFetch()) ne fournit pas un moyen "propre" de passer des paramètres. Nous devrons construire manuellement la chaîne de requête GET dans ‘path’, comme je l’ai fait ci-dessus : '../getsomedata?product_id=14'.

Si vous souhaitez savoir comment incorporer wp.apiFetchet personnaliser des points de terminaison dans un bloc Gutenberg, j’ai écrit un tutoriel séparé à ce sujet :

Utilisation de Javascript vanille

Comme dernier exemple de méthodes Javascript pour envoyer une requête à l’API WP REST, il existe une manière purement vanille, non-WordPress, d’utiliser fetch(). Veuillez noter que j’utilise la variable globale WordPress pour obtenir l’URL racine REST. Si vous ajoutez ce script en dehors de WordPress, vous devrez probablement coder en dur l’URL complète.

Puisque je veux toujours accéder à la variable globale pour l’URL racine WP REST, j’ajoute 'wp-api-request'une dépendance à ma fonction de mise en file d’attente Javascript, comme suit :

add_action( 'wp_enqueue_scripts', function() {
    wp_enqueue_script(
        'awp-javascript-wp-rest', 
        get_stylesheet_directory_uri(). '/assets/js/javascript_wp_rest.js', 
        [ 'wp-api-request' ], 
        null, 
        true
    );
} );

Et puis dans notre fichier Javascript un exemple le plus basique serait :

Comme mentionné ci-dessus ("Utilisation de la bibliothèque WordPress") .fetch()ne prend pas en charge une manière agréable et propre de fournir des paramètres. Vous devrez donc créer manuellement la chaîne de requête ("?product_id=14") dans l’URL.

Gardez à l’esprit que la requête d’extraction ne revient pas directement avec les données – elle renvoie une promesse. C’est pourquoi nous devons enchaîner " .then()" avant de pouvoir gérer les données. Si cela ne vous semble pas familier, je vous recommande de rechercher comment travailler avec fetch()– il existe de nombreuses explications et exemples sur Google qui peuvent l’expliquer mieux que moi.

Si vous souhaitez vérifier le code d’état de la réponse REST à votre demande, vous pouvez le faire ainsi ;

Dans l’exemple ci-dessus lors de l’enregistrement de points de terminaison personnalisés, j’ai mentionné comment vous pouvez renvoyer différents codes d’état HTTP. Le code ci-dessus montre un exemple de vérification du code d’état de la réponse, qui est disponible dans la .statuspropriété de l’objet renvoyé. Dans l’exemple ci-dessus, je vérifie si le code d’état est différent de 200 (Succès) à la ligne #5. Ce n’est que si le code d’état était 200 que je convertis le retour de données de la promesse en JSON (ligne #9).

Utiliser PHP

Il est moins courant, mais toujours possible, d’effectuer une requête REST en interne dans WordPress en utilisant PHP. Voici comment.

Afin d’envoyer une requête WP REST API en PHP, nous créons un WP_REST_Requestobjet (exactement comme ce qui est passé à notre fonction de rappel plus tôt dans ce post). Dans cette instance d’objet, nous définissons la méthode (par exemple GET) et le chemin du point de terminaison. En option, nous pouvons également ajouter des paramètres. Ensuite, nous utilisons la fonction WordPress [rest_do_request](https://developer.wordpress.org/reference/functions/rest_do_request/)()avec cette instance de requête. Enfin, nous obtenons la réponse avec la [response_to_data](https://developer.wordpress.org/reference/classes/wp_rest_server/response_to_data/)()fonction disponible dans WP_REST_Server'la classe s.

L’appel de fonction set_query_params()(line #3-5) est facultatif et uniquement nécessaire si vous souhaitez passer des paramètres. En suivant le fil rouge de cet article, j’inclurai un exemple de transmission du paramètre de la fonction à la clé de paramètre REST product_id.

La ligne #6est l’endroit où nous envoyons la demande. Et à la ligne #7nous renvoyons les données de la réponse. Donc, si nous devions appeler cette fonction PHP, par exemple, awp_do_php_rest_request( 14 )nous obtiendrions alors la réponse que nous avons définie dans ce point de terminaison (un tableau avec une chaîne si vous utilisez toujours le même exemple qu’au début de cet article).