Combien de vérifications faut-il vraiment avant de laisser une route REST maison quitter l’environnement de développement ? La question mérite d’être posée, parce que register_rest_route() se prend en main en quelques minutes, mais ses détails d’implémentation déterminent si l’endpoint tiendra face à un trafic réel ou s’effondrera au premier appel malformé.
Cette liste s’adresse à un développeur qui construit sa première route pour un projet headless, avant même de penser au cache ou à la montée en charge. Elle couvre uniquement ce qui doit être vérifié avant la mise en ligne, point par point.
1. La route est-elle correctement namespacée ?
Un namespace personnalisé, du type mon-projet/v1, évite toute collision avec les routes du cœur ou d’une extension tierce. Le versionnage dans le namespace n’est pas cosmétique : il permet de faire coexister une v1 et une v2 le temps d’une migration côté front, sans casser les clients existants.
register_rest_route( 'mon-projet/v1', '/menu', array(
'methods' => WP_REST_Server::READABLE,
'callback' => 'mon_projet_get_menu',
'permission_callback' => '__return_true',
) );2. permission_callback a-t-elle été pensée, pas juste renseignée ?
Depuis WordPress 4.7, omettre permission_callback déclenche un avertissement dans les journaux, précisément parce que cet oubli a longtemps ouvert des routes sans aucun contrôle d’accès. Renseigner __return_true pour un contenu public est légitime ; le faire par réflexe sur une route qui expose des données privées ne l’est pas.
3. Le schéma des arguments est-il déclaré ?
Un argument sans validate_callback ni sanitize_callback transmet tel quel n’importe quelle valeur à la fonction de callback. Déclarer le type attendu, une valeur par défaut et un callback de validation évite une bonne partie des vérifications manuelles à l’intérieur de la fonction elle-même.
- Type déclaré explicitement (
integer,string,boolean) validate_callbackpour rejeter une valeur hors périmètre avant l’exécutionsanitize_callbackpour nettoyer une chaîne avant tout usage en base- Valeur par défaut cohérente pour les paramètres optionnels
4. Les erreurs renvoient-elles un objet WP_Error correctement codé ?
Un endpoint qui retourne systématiquement un code 200, même en cas d’échec, complique inutilement la vie du front qui le consomme. Une ressource introuvable doit renvoyer un WP_Error avec le code rest_not_found et un statut HTTP 404, une requête refusée un statut 403.
if ( ! $item ) {
return new WP_Error(
'rest_not_found',
__( 'Ressource introuvable.', 'mon-projet' ),
array( 'status' => 404 )
);
}Table de correspondance rapide
| Situation | Code WP_Error | Statut HTTP |
|---|---|---|
| Ressource absente | rest_not_found | 404 |
| Accès refusé | rest_forbidden | 403 |
| Paramètre invalide | rest_invalid_param | 400 |
5. La réponse a-t-elle été testée hors du navigateur ?
Tester une route uniquement via l’onglet réseau du navigateur masque souvent des erreurs de sérialisation JSON qui n’apparaissent qu’avec certains caractères spéciaux dans le contenu. Un appel direct avec curl ou avec la commande wp rest côté serveur donne une image plus fidèle de ce que recevra réellement un front headless.
Une route qui fonctionne dans le navigateur de son auteur n’a encore rien prouvé ; elle doit survivre à un appel depuis un terminal vide de tout cookie de session.
6. La documentation de la route existe-t-elle quelque part ?
Un simple commentaire au-dessus de register_rest_route() décrivant les paramètres acceptés et le format de la réponse suffit largement pour un projet de taille modeste. L’absence totale de documentation, même minimale, se paie systématiquement au moment où quelqu’un d’autre doit consommer ou maintenir cette route.
En résumé
Namespace versionné, permission_callback réfléchie, schéma d’arguments complet, erreurs correctement codées, test hors navigateur, documentation minimale : ces six points suffisent à éviter la majorité des déconvenues du premier endpoint REST personnalisé. Cette liste ne traite volontairement pas de la mise en cache des réponses, qui relève d’une étape ultérieure une fois la route stabilisée.
