# Checklist avant d’exposer un premier endpoint REST personnalisé

> Combien de points faut-il vérifier avant qu'une route register_rest_route ne parte en production ? Une liste commentée pour éviter les mauvaises surprises du premier déploiement.

- Auteur : WordPress Développement
- Publié le : 2020-02-27
- Mis à jour le : 2020-02-27
- Catégorie : Headless & API
- URL : https://www.wpmoderne.fr/headless/checklist-avant-exposer-endpoint-rest-personnalise/

## L’essentiel

- Un schéma explicite évite bien des validations manuelles
- permission_callback n'est jamais optionnelle
- Les erreurs doivent renvoyer un code HTTP cohérent

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.

> L'essentiel à retenir : Un schéma explicite évite bien des validations manuelles ; permission_callback n'est jamais optionnelle ; Les erreurs doivent renvoyer un code HTTP cohérent

## 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_callback` pour rejeter une valeur hors périmètre avant l'exécution
- `sanitize_callback` pour 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.