fswp-api-developer

Développeur API FSWP

Fondamental (toujours appliqué) : fswp-developer/references/lean-coding.md (écrire moins, réutiliser d'abord), fswp-developer/references/coding-standards.md (normes de codage, documentation, i18n, accessibilité), et fswp-security-engineer (entrée, sortie, autorisation).

Référence officielle : Guide de l'API REST (fswp-developer/references/official-docs.md). Les règles de sécurité dans fswp-security-engineer s'appliquent à chaque route.

Enregistrer une route

function vp_register_routes() {
	register_rest_route( 'vendor-prefix/v1', '/items/(?P<id>\d+)', array(
		'methods'             => WP_REST_Server::READABLE,
		'callback'            => 'vp_get_item',
		'permission_callback' => function ( WP_REST_Request $r ) {
			return current_user_can( 'edit_post', (int) $r['id'] );
		},
		'args'                => array(
			'id' => array( 'type' => 'integer', 'required' => true, 'sanitize_callback' => 'absint' ),
		),
	) );
}
add_action( 'rest_api_init', 'vp_register_routes' );

Règles

• Espace de nommage et version : vendor-prefix/v1. Ne jamais enregistrer dans l'espace de nommage wp/v2 de WordPress.
• permission_callback est obligatoire. Retourne une vérification de capacité, pas seulement l'état de connexion. Utilise __return_true uniquement pour des données réellement publiques, avec un commentaire expliquant pourquoi. Vérifie l'accès au niveau de l'objet (edit_post, propriété) chaque fois qu'un ID est présent dans la requête.
• Déclare les args avec type, required, enum, minimum/maximum, validate_callback et sanitize_callback. La requête n'est pas fiable même après validation ; utilise les valeurs de $request->get_param() telles qu'elles sont typées.
• Retourne les données avec rest_ensure_response() ; les erreurs sous forme de new WP_Error( 'vp_code', __( 'Message', 'text-domain' ), array( 'status' => 404 ) ). Utilise des codes de statut précis (400 invalide, 401 non authentifié, 403 interdit, 404 manquant, 409 conflit, 413 trop volumineux).
• Schéma : implémente get_item_schema() (ou le callback schema) pour que les clients et l'index puissent décrire la ressource ; formate les réponses avec prepare_item_for_response().
• Collections : prend en charge page/per_page avec une limite maximale, définit X-WP-Total et X-WP-TotalPages, et ne retourne jamais de listes non limitées.
• Ne jamais retourner de secrets, de hachages de mots de passe, d'options brutes ou de données privées d'autres utilisateurs.
• Contrôleurs : pour plus de quelques routes, étends WP_REST_Controller (register_routes, get_items, get_item, create_item, vérifications de permission par méthode) et enregistre la classe une fois.
• Exposer les objets de base : types de publication personnalisés et taxonomies avec 'show_in_rest' => true (et rest_base) ; métadonnées avec register_meta()/register_post_meta() et 'show_in_rest' => true ainsi qu'un schéma et un auth_callback.
• Mise en cache et performance : gestionnaires GET légers ; mets en cache les résultats coûteux (fswp-performance-engineer) ; évite les requêtes dans les boucles.

Authentification

Client	Méthode
JS sur le même site (admin, blocs, front-end)	Authentification par cookie avec l'en-tête X-WP-Nonce (wp_create_nonce( 'wp_rest' ), ou wp_localize_script / @wordpress/api-fetch qui l'ajoute)
Serveur externe ou application	Mots de passe d'application via HTTPS, ou un plugin OAuth approuvé
Lecture publique	Aucune authentification, uniquement lorsque les données sont publiques

Les nonces ne remplacent pas les vérifications de capacité. CORS : n'ouvre pas Access-Control-Allow-Origin: * sur les routes authentifiées.

Côté client

Utilise @wordpress/api-fetch dans les blocs et les écrans d'administration. Gère les erreurs par code et message, pas en analysant le texte.

API Abilities

Une API Core pour enregistrer des capacités discrètes et lisibles par machine (nom, schéma d'entrée, schéma de sortie, vérification de permission, callback d'exécution) que les outils et agents IA peuvent découvrir et appeler. Elle est récente : confirme la version minimale de WordPress et les noms de fonctions exacts dans la documentation développeur avant de l'utiliser (recherche "Abilities API"). Utilise-la uniquement lorsque le PRD nécessite des fonctions appelables par un agent ; l'API REST classique est adaptée aux appels client-serveur ordinaires.

Lors de l'enregistrement d'une ability :

• Enregistre d'abord la catégorie, puis l'ability, sur les hooks documentés.
• Fournis des schémas JSON pour l'entrée et la sortie, et un permission_callback qui vérifie une capacité réelle.
• Définis honnêtement les annotations de sécurité : les abilities read-only ne doivent pas écrire, les destructives doivent être signalées. Un callback qui écrit alors qu'il est annoté read-only est un défaut, et fswp-reviewer le traite comme tel.
• Expose via REST uniquement ce qui doit pouvoir être appelé à distance.

Procédures d'audit et de vérification : references/abilities.md.

Pour proposer quels points de terminaison existants devraient devenir des abilities, liste chaque route avec sa méthode, sa vérification de permission actuelle, ses effets secondaires et une annotation suggérée ; n'enregistre rien avant approbation.