fswp-api-developer

Desenvolvedor de API FSWP

Fundamental (sempre aplicado): fswp-developer/references/lean-coding.md (escreva menos, reutilize primeiro), fswp-developer/references/coding-standards.md (padrões de codificação, documentação, i18n, acessibilidade) e fswp-security-engineer (entrada, saída, autorização).

Referência oficial: Manual da REST API (fswp-developer/references/official-docs.md). As regras de segurança em fswp-security-engineer se aplicam a toda rota.

Registrar uma rota

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

Regras

• Namespace e versão: vendor-prefix/v1. Nunca registre no namespace wp/v2 do core.
• permission_callback é obrigatório. Retorne uma verificação de capability, não apenas o status de login. Use __return_true apenas para dados genuinamente públicos, com um comentário explicando o motivo. Verifique acesso ao nível do objeto (edit_post, propriedade) sempre que um ID estiver na requisição.
• Declare args com type, required, enum, minimum/maximum, validate_callback e sanitize_callback. A requisição não é confiável mesmo após a validação; use valores de $request->get_param() com seus tipos.
• Retorne dados com rest_ensure_response(); erros como new WP_Error( 'vp_code', __( 'Mensagem', 'text-domain' ), array( 'status' => 404 ) ). Use códigos de status precisos (400 inválido, 401 não autenticado, 403 proibido, 404 ausente, 409 conflito, 413 muito grande).
• Esquema: implemente get_item_schema() (ou callback schema) para que clientes e o índice possam descrever o recurso; modele as respostas com prepare_item_for_response().
• Coleções: suporte page/per_page com um limite máximo, defina X-WP-Total e X-WP-TotalPages, e nunca retorne listas ilimitadas.
• Nunca retorne segredos, hashes de senha, opções brutas ou dados privados de outros usuários.
• Controladores: para mais de duas rotas, estenda WP_REST_Controller (register_routes, get_items, get_item, create_item, verificações de permissão por método) e registre a classe uma vez.
• Exponha objetos do core: tipos de post personalizados e taxonomias com 'show_in_rest' => true (e rest_base); meta com register_meta()/register_post_meta() e 'show_in_rest' => true além de um esquema e um auth_callback.
• Cache e desempenho: manipuladores GET leves; armazene resultados caros em cache (fswp-performance-engineer); evite consultas em loops.

Autenticação

Cliente	Método
JavaScript no mesmo site (admin, blocos, front-end)	Autenticação por cookie com o cabeçalho X-WP-Nonce (wp_create_nonce( 'wp_rest' ), ou wp_localize_script / @wordpress/api-fetch que o adiciona)
Servidor ou aplicativo externo	Senhas de aplicativo via HTTPS, ou um plugin OAuth verificado
Leitura pública	Sem autenticação, apenas quando os dados são públicos

Nonces não substituem verificações de capability. CORS: não abra Access-Control-Allow-Origin: * em rotas autenticadas.

Lado do cliente

Use @wordpress/api-fetch em blocos e telas administrativas. Trate erros por code e message, não analisando texto.

API de Habilidades (Abilities API)

Uma API do Core para registrar capacidades discretas e legíveis por máquina (nome, esquema de entrada, esquema de saída, verificação de permissão, callback de execução) que ferramentas e agentes de IA podem descobrir e chamar. É recente: confirme a versão mínima do WordPress e os nomes exatos das funções na documentação do desenvolvedor antes de usá-la (pesquise "Abilities API"). Use-a apenas quando o PRD precisar de funções chamáveis por agentes; REST simples é adequado para chamadas comuns cliente-servidor.

Ao registrar uma habilidade:

• Registre a categoria primeiro, depois a habilidade, nos hooks documentados.
• Forneça JSON Schemas para entrada e saída, e um permission_callback que verifique uma capability real.
• Defina as anotações de segurança honestamente: habilidades somente leitura não devem escrever, habilidades destrutivas devem ser sinalizadas. Um callback que escreve enquanto anotado como somente leitura é um defeito, e fswp-reviewer o trata como tal.
• Exponha via REST apenas o que deve ser chamável remotamente.

Procedimentos de auditoria e verificação: references/abilities.md.

Para propor quais endpoints existentes devem se tornar habilidades, liste cada rota com seu método, verificação de permissão atual, efeitos colaterais e uma anotação sugerida; não registre nada até que seja aprovado.