WP REST API

Quand l'utiliser

Utilise cette skill lorsque tu dois :

• créer ou mettre à jour des routes/endpoints REST
• déboguer des erreurs 401/403/404 ou des problèmes de permission/nonce
• ajouter des champs personnalisés/meta aux réponses REST
• exposer des custom post types ou taxonomies via REST
• implémenter la validation de schéma et d'arguments
• ajuster les liens de réponse/embedding/pagination

Entrées requises

• Racine du repo + plugin/thème/mu-plugin cible (chemin vers le point d'entrée).
• Namespace et version souhaités (ex. my-plugin/v1) et routes.
• Mode d'authentification (cookie + nonce vs application passwords vs plugin d'auth).
• Contraintes de version WordPress (si inférieure à 6.9, à signaler).

Procédure

0) Triage et localisation de l'utilisation REST

1. Lance le triage :
   • node skills/wp-project-triage/scripts/detect_wp_project.mjs
2. Recherche l'utilisation REST existante :
   • register_rest_route
   • WP_REST_Controller
   • rest_api_init
   • show_in_rest, rest_base, rest_controller_class

S'il s'agit d'un repo full site, sélectionne le plugin/thème spécifique avant de modifier le code.

1) Choisir la bonne approche

• Exposer un CPT/taxonomy dans wp/v2 :
  • Utilise show_in_rest => true + rest_base si nécessaire.
  • Fournis optionnellement rest_controller_class.
  • Lis references/custom-content-types.md.
• Endpoints personnalisés :
  • Utilise register_rest_route() sur rest_api_init.
  • Préfère une classe controller (WP_REST_Controller subclass) pour tout ce qui n'est pas trivial.
  • Lis references/routes-and-endpoints.md et references/schema.md.

2) Enregistrer les routes de manière sûre (namespaces, méthodes, permissions)

• Utilise un namespace unique vendor/v1 ; évite wp/* sauf pour le core.
• Fournis toujours permission_callback (utilise __return_true pour les endpoints publics).
• Utilise les constantes WP_REST_Server::READABLE/CREATABLE/EDITABLE/DELETABLE.
• Retourne les données via rest_ensure_response() ou WP_REST_Response.
• Retourne les erreurs via WP_Error avec un status explicite.

Lis references/routes-and-endpoints.md.

3) Valider/nettoyer les arguments de requête

• Définis args avec type, default, required, validate_callback, sanitize_callback.
• Préfère la validation JSON Schema avec rest_validate_value_from_schema puis rest_sanitize_value_from_schema.
• Ne lis jamais $_GET/$_POST directement dans les endpoints ; utilise WP_REST_Request.

Lis references/schema.md.

4) Réponses, champs et liens

• Ne supprime pas les champs core des endpoints par défaut ; ajoute des champs à la place.
• Utilise register_rest_field pour les champs calculés ; register_meta avec show_in_rest pour la meta.
• Pour la meta object/array, définis le schéma dans show_in_rest.schema.
• Si tu as besoin du contenu post non filtré (ex. plugins ToC injectant du HTML), demande ?context=edit pour accéder à content.raw (authentification requise). Associe avec _fields=content.raw pour limiter la taille des réponses.
• Ajoute les liens de ressources associées via WP_REST_Response::add_link().

Lis references/responses-and-fields.md.

5) Authentification et autorisation

• Pour wp-admin/JS : cookie auth + X-WP-Nonce (action wp_rest).
• Pour les clients externes : application passwords (basic auth) ou un plugin d'auth.
• Utilise les vérifications de capacité dans permission_callback (autorisation), pas juste « connecté ».

Lis references/authentication.md.

6) Comportement côté client (découverte, pagination, embeds)

• Assure-toi que la découverte fonctionne (en-tête Link ou <link rel="https://api.w.org/">).
• Supporte _fields, _embed, _method, _envelope, en-têtes de pagination.
• Souviens-toi que per_page est limité à 100.

Lis references/discovery-and-params.md.

Vérification

• /wp-json/ index inclut ton namespace.
• OPTIONS sur ta route retourne le schéma (si fourni).
• L'endpoint retourne les données attendues ; les défauts de permission retournent 401/403 comme approprié.
• Les routes CPT/taxonomy apparaissent sous wp/v2 quand show_in_rest est true.
• Lance le lint/tests du repo et toute étape de build PHP/JS.

Modes de défaillance / débogage

• 404 : rest_api_init ne se déclenche pas, typo dans la route, ou les permaliens sont désactivés (utilise ?rest_route=).
• 401/403 : nonce/auth manquant, ou permission_callback trop strict.
• _doing_it_wrong pour permission_callback manquant : ajoute-le (utilise __return_true si public).
• Paramètres invalides : schéma args manquant/incorrect ou callbacks de validation.
• Champs manquants : show_in_rest false, meta non enregistrée, ou CPT sans support custom-fields.

Escalade

Si le support de version ou le comportement n'est pas clair, consulte le REST API Handbook et la documentation du core avant d'inventer des patterns.