Créer une route personnalisée avec l'API WordPress

Pourquoi créer une route personnalisée dans l’API WordPress ?

L’API WordPress native couvre déjà la majorité des besoins standards : récupération d’articles, de pages, gestion des utilisateurs ou encore des commentaires. Cependant, dès que vous entamez le développement plugin WP sur mesure ou que vous transformez WordPress en solution headless, ces routes par défaut peuvent s’avérer insuffisantes ou mal optimisées.

Créer un point de terminaison (ou endpoint personnalisé) permet de :

• Réduire la charge serveur : en ne retournant que les données strictement nécessaires, plutôt que l’objet complet d’un article.
• Agréger des données : compiler des informations provenant de plusieurs tables ou Custom Post Types en une seule requête HTTP.
• Exécuter des actions métier : déclencher un script spécifique, envoyer un email ou synchroniser un CRM via une requête POST.

Diagramme du mecanisme de l’api de wordpress lors d’ l’enregistrment d’une route personnalisee

Étape 1 : Déclarer la route avec le hook rest_api_init

Dans WordPress, toute modification de l’API REST doit être accrochée au hook rest_api_init. Cela garantit que votre code ne s’exécute que lorsque l’API est effectivement chargée.

Ajoutez ce code dans le fichier principal de votre plugin ou dans le functions.php de votre thème enfant :

add_action( 'rest_api_init', 'nc_register_custom_endpoints' );

function nc_register_custom_endpoints() {
    // La déclaration de la route se fera ici
}

Étape 2 : Configurer register_rest_route pour appeler L’API

La fonction register_rest_route() est le cœur de la création de votre WordPress REST API personnalisé. Elle accepte trois paramètres principaux :

• l’espace de noms (namespace)
• la route
• et un tableau d’arguments

L’espace de noms et le versioning

Il est crucial de toujours préfixer vos routes avec un espace de noms unique (souvent le nom de votre plugin) suivi d’un numéro de version. Cela évite les conflits avec d’autres extensions.

function nc_register_custom_endpoints() {
    register_rest_route( 'noucode/v1', '/statistiques/(?P<id>\d+)', array(
        'methods'             => WP_REST_Server::READABLE, // Équivaut à 'GET'
        'callback'            => 'nc_get_custom_stats',
        'permission_callback' => 'nc_check_api_permissions',
        'args'                => array(
            'id' => array(
                'validate_callback' => function($param, $request, $key) {
                    return is_numeric( $param );
                }
            ),
        ),
    ) );
}

Dans cet exemple, nous utilisons une expression régulière (?P<id>\d+) pour capturer un paramètre dynamique (un ID numérique) directement dans l’URL.

Étape 3 : Créer la fonction de rappel (Callback)

La fonction de rappel est exécutée lorsque l’endpoint est appelé. Elle reçoit un objet WP_REST_Request contenant toutes les informations de la requête HTTP.

Votre fonction doit traiter les données et retourner un objet WP_REST_Response, ou une instance de WP_Error en cas de problème.

function nc_get_custom_stats( WP_REST_Request $request ) {
    // Récupération du paramètre d'URL
    $post_id = $request->get_param( 'id' );

    // Vérification de l'existence de l'article
    if ( ! get_post_status( $post_id ) ) {
        return new WP_Error(
            'no_post',
            'Aucun article trouvé pour cet ID.',
            array( 'status' => 404 )
        );
    }

    // Simulation de récupération de données métier
    $vues = get_post_meta( $post_id, '_nc_post_views', true ) ?: 0;
    
    $data = array(
        'post_id' => (int) $post_id,
        'views'   => (int) $vues,
        'status'  => 'success'
    );

    // Retourne une réponse JSON avec un code HTTP 200
    return new WP_REST_Response( $data, 200 );
}

Étape 4 : Sécuriser l’accès avec permission_callback

Depuis les versions récentes de WordPress, omettre le permission_callback génère une erreur dans les logs. Ce paramètre est indispensable pour sécuriser votre endpoint personnalisé.

Si la route doit être publique, vous devez explicitement retourner true. Si elle nécessite des droits, utilisez les capacités de l’utilisateur.

function nc_check_api_permissions( WP_REST_Request $request ) {
    // Exemple : Restreindre l'accès aux administrateurs ou éditeurs
    if ( ! current_user_can( 'edit_posts' ) ) {
        return new WP_Error(
            'rest_forbidden',
            'Vous n\'avez pas les droits nécessaires pour voir ces statistiques.',
            array( 'status' => rest_authorization_required_code() )
        );
    }
    
    return true;
}

Note : Pour une route 100 % publique, vous pouvez utiliser la fonction native de WordPress : 'permission_callback' => '__return_true'.

Tester votre nouveau point de terminaison REST

Une fois le code en place, vous pouvez tester votre API. Si vous utilisez un environnement local (comme Docker ou LocalWP), l’URL ressemblera à ceci :

https://votre-site.local/wp-json/noucode/v1/statistiques/42

Vous pouvez effectuer ce test via :

• Postman ou Insomnia : Idéal pour tester les requêtes nécessitant une authentification (via Application Passwords ou JWT).
• cURL : Directement depuis votre terminal.
• Votre navigateur : Uniquement si la route est en méthode GET et publique.

Bonnes pratiques pour le développement d’API WordPress

Pour maintenir un code propre et performant lors de la création de vos endpoints :

1. Versionnez vos routes : N’utilisez jamais /v1/ de manière définitive. Si la structure de vos données change drastiquement à l’avenir, créez un /v2/ pour ne pas casser les applications existantes.
2. Validez et nettoyez les paramètres : Utilisez les arguments validate_callback et sanitize_callback dans register_rest_route pour vous assurer que les données reçues sont sûres avant même qu’elles n’atteignent votre fonction principale.
3. Utilisez les constantes HTTP : Préférez WP_REST_Server::READABLE, CREATABLE, ou EDITABLE plutôt que d’écrire ‘GET’ ou ‘POST’ en dur.
4. Mettez en cache les réponses lourdes : Si votre endpoint exécute des requêtes SQL complexes, utilisez l’API Transients de WordPress pour mettre en cache le résultat et améliorer les temps de réponse.