fswp-api-developer

Desarrollador de API FSWP

Fundamental (siempre aplicado): fswp-developer/references/lean-coding.md (escribe menos, reutiliza primero), fswp-developer/references/coding-standards.md (estándares de codificación, documentación, i18n, accesibilidad) y fswp-security-engineer (entrada, salida, autorización).

Referencia oficial: Manual de la API REST (fswp-developer/references/official-docs.md). Las reglas de seguridad de fswp-security-engineer se aplican a cada ruta.

Registrar una ruta

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' );

Reglas

• Espacio de nombres y versión: vendor-prefix/v1. Nunca registrar en el espacio de nombres wp/v2 del núcleo.
• permission_callback es obligatorio. Devuelve una comprobación de capacidad, no solo el estado de inicio de sesión. Usa __return_true solo para datos genuinamente públicos, con un comentario explicando por qué. Verifica el acceso a nivel de objeto (edit_post, propiedad) siempre que haya un ID en la solicitud.
• Declara args con type, required, enum, minimum/maximum, validate_callback y sanitize_callback. La solicitud no es de confianza incluso después de la validación; usa los valores de $request->get_param() como están tipados.
• Devuelve datos con rest_ensure_response(); errores como new WP_Error( 'vp_code', __( 'Mensaje', 'text-domain' ), array( 'status' => 404 ) ). Usa códigos de estado precisos (400 inválido, 401 no autenticado, 403 prohibido, 404 no encontrado, 409 conflicto, 413 demasiado grande).
• Esquema: implementa get_item_schema() (o callback schema) para que los clientes y el índice puedan describir el recurso; da forma a las respuestas con prepare_item_for_response().
• Colecciones: soporta page/per_page con un límite máximo, establece X-WP-Total y X-WP-TotalPages, y nunca devuelvas listas sin límite.
• Nunca devuelvas secretos, hashes de contraseñas, opciones sin procesar ni datos privados de otros usuarios.
• Controladores: para más de un par de rutas, extiende WP_REST_Controller (register_routes, get_items, get_item, create_item, comprobaciones de permisos por método) y registra la clase una vez.
• Exponer objetos del núcleo: tipos de contenido personalizados y taxonomías con 'show_in_rest' => true (y rest_base); metadatos con register_meta()/register_post_meta() y 'show_in_rest' => true más un esquema y un auth_callback.
• Caché y rendimiento: manejadores GET ligeros; almacena en caché resultados costosos (fswp-performance-engineer); evita consultas en bucles.

Autenticación

Cliente	Método
JS del mismo sitio (admin, bloques, front end)	Autenticación por cookie con la cabecera X-WP-Nonce (wp_create_nonce( 'wp_rest' ), o wp_localize_script / @wordpress/api-fetch que lo añade)
Servidor o aplicación externa	Contraseñas de aplicación sobre HTTPS, o un plugin OAuth verificado
Lectura pública	Sin autenticación, solo cuando los datos sean públicos

Los nonces no reemplazan las comprobaciones de capacidad. CORS: no abras Access-Control-Allow-Origin: * en rutas autenticadas.

Lado del cliente

Usa @wordpress/api-fetch en bloques y pantallas de administración. Maneja los errores por code y message, no analizando texto.

API de Habilidades

Una API del núcleo para registrar capacidades discretas y legibles por máquina (nombre, esquema de entrada, esquema de salida, comprobación de permisos, callback de ejecución) que las herramientas y los agentes de IA puedan descubrir y llamar. Es reciente: confirma la versión mínima de WordPress y los nombres exactos de las funciones en la documentación del desarrollador antes de usarla (busca "Abilities API"). Úsala solo cuando el PRD necesite funciones invocables por agentes; la REST simple es adecuada para llamadas normales cliente-servidor.

Al registrar una habilidad:

• Registra la categoría primero, luego la habilidad, en los hooks documentados.
• Proporciónale esquemas JSON para entrada y salida, y un permission_callback que verifique una capacidad real.
• Configura las anotaciones de seguridad honestamente: las habilidades de solo lectura no deben escribir, las destructivas deben ser marcadas. Un callback que escriba mientras está anotado como solo lectura es un defecto, y fswp-reviewer lo trata como tal.
• Expón a través de REST solo lo que deba ser invocable de forma remota.

Procedimientos de auditoría y verificación: references/abilities.md.

Para proponer qué endpoints existentes deberían convertirse en habilidades, enumera cada ruta con su método, comprobación de permisos actual, efectos secundarios y una anotación sugerida; no registres nada hasta que sea aprobado.