Schéma REST API (JSON Schema)
Définition : Un schéma REST WordPress décrit la forme des données attendues ou retournées par un endpoint. Il précise les types, les propriétés, les contraintes et parfois les contextes de visibilité.
Comprendre et utiliser
À quoi sert cette notion ?
Il sert de contrat vérifiable entre client et serveur. Il aide à rejeter les valeurs incorrectes et à documenter les ressources sans se limiter à un exemple JSON informel.
Fonctionnement technique
WordPress prend en charge un sous-ensemble de JSON Schema. Les descriptions peuvent définir type, required, enum, minimum ou d’autres contraintes reconnues selon la version du Core.
Dans quel contexte l’utiliser ?
Un endpoint de notes accepte un champ priorité entier entre 1 et 5 afin d’éviter des états incohérents.
Étude de cas : application professionnelle
Pour une API de dossiers, un champ de priorité doit être limité à des entiers de 1 à 5. Définir cette règle dans un schéma permet au serveur de la communiquer et de la contrôler. Ajouter ensuite une propriété facultative, par exemple une note, en distinguant son absence de sa valeur vide. Tester les bornes et les erreurs de type. Un schéma ne remplace toutefois pas une autorisation ou une règle métier : un utilisateur sans droit ne peut pas modifier la priorité même si son JSON respecte parfaitement le format annoncé.
Exemple technique commenté
Ce fragment représente des données de schéma, pas un fichier de configuration WordPress autonome. Il doit être intégré au contrat d'une route ou d'un contrôleur, puis vérifié dans la version WordPress ciblée. Contrôler les comportements de validation et les messages retournés en cas de propriété manquante.
{"type":"object","properties":{"priorite":{"type":"integer","minimum":1,"maximum":5}},"required":["priorite"]}Décryptage du code et résultat attendu
Le schéma exige une propriété priorité numérique entière et bornée. Il constitue un exemple de contrat ; son application suppose un endpoint qui l’utilise effectivement.
Exercice guidé pour vérifier la notion
Tester des valeurs 3, 0, 6 et « urgent » afin d’observer quels cas doivent être refusés.
Précautions et limites
Ne pas supposer la conformité complète à toutes les versions de la spécification JSON Schema : consulter les mots-clés réellement supportés par WordPress.
À ne pas confondre
Le schéma valide la forme ; l’autorisation vérifie les droits et la logique métier vérifie le sens d’une opération.
Diagnostic avancé
Si un objet inattendu traverse la validation, inspecter la déclaration des propriétés et les contraintes supportées par la version ciblée.
Choix d’architecture et déploiement
Rédiger les schémas avant les callbacks d’écriture et les conserver compatibles avec les clients qui consomment déjà la version publiée.
