FSWP API 개발자
기본 (항상 적용): fswp-developer/references/lean-coding.md (적게 작성하고 재사용 우선), fswp-developer/references/coding-standards.md (코딩 표준, 문서, i18n, 접근성), fswp-security-engineer (입력, 출력, 인가).
공식 참조: REST API 핸드북 (fswp-developer/references/official-docs.md). fswp-security-engineer의 보안 규칙은 모든 경로에 적용됩니다.
경로 등록
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' );
규칙
- 네임스페이스 및 버전:
vendor-prefix/v1. 코어의wp/v2네임스페이스에 절대 등록하지 마세요. permission_callback는 필수입니다. 로그인 상태 확인이 아닌 기능(capability) 검사를 반환하세요. 진정으로 공개적인 데이터에만__return_true를 사용하고, 그 이유를 설명하는 주석을 추가하세요. 요청에 ID가 포함된 경우 객체 수준 접근(edit_post, 소유권)을 확인하세요.args선언 시type,required,enum,minimum/maximum,validate_callback,sanitize_callback을 포함하세요. 요청은 검증 후에도 신뢰할 수 없으므로$request->get_param()값을 타입화된 대로 사용하세요.- 데이터 반환은
rest_ensure_response()로; 오류는new WP_Error( 'vp_code', __( '메시지', 'text-domain' ), array( 'status' => 404 ) )로 처리하세요. 정확한 상태 코드를 사용하세요 (400 잘못된 요청, 401 인증되지 않음, 403 금지됨, 404 찾을 수 없음, 409 충돌, 413 너무 큼). - 스키마: 클라이언트와 인덱스가 리소스를 설명할 수 있도록
get_item_schema()(또는schema콜백)을 구현하고,prepare_item_for_response()로 응답을 구성하세요. - 컬렉션: 하드 상한이 있는
page/per_page를 지원하고,X-WP-Total및X-WP-TotalPages헤더를 설정하며, 무제한 목록을 절대 반환하지 마세요. - 비밀 정보, 비밀번호 해시, 원시 옵션, 다른 사용자의 개인 데이터를 절대 반환하지 마세요.
- 컨트롤러: 경로가 몇 개 이상이면
WP_REST_Controller를 확장하여 (register_routes,get_items,get_item,create_item, 메서드별 권한 검사) 클래스를 한 번 등록하세요. - 코어 객체 노출: 사용자 정의 포스트 타입과 분류는
'show_in_rest' => true(및rest_base)로; 메타는register_meta()/register_post_meta()와'show_in_rest' => true, 스키마,auth_callback로 노출하세요. - 캐싱 및 성능:
GET핸들러는 가볍게 유지하고, 비용이 많이 드는 결과는 캐시하세요 (fswp-performance-engineer); 반복문 내에서 쿼리를 피하세요.
인증
| 클라이언트 | 방법 |
|---|---|
| 동일 사이트 JS (관리자, 블록, 프런트 엔드) | X-WP-Nonce 헤더를 사용한 쿠키 인증 (wp_create_nonce( 'wp_rest' ), 또는 wp_localize_script / @wordpress/api-fetch에서 자동 추가) |
| 외부 서버 또는 앱 | HTTPS를 통한 애플리케이션 비밀번호, 또는 검증된 OAuth 플러그인 |
| 공개 읽기 | 데이터가 공개적인 경우에만 인증 없음 |
논스는 기능(capability) 검사를 대체하지 않습니다. CORS: 인증된 경로에 Access-Control-Allow-Origin: *를 열지 마세요.
클라이언트 측
블록 및 관리자 화면에서 @wordpress/api-fetch를 사용하세요. 오류는 텍스트를 파싱하지 말고 code와 message로 처리하세요.
Abilities API
도구와 AI 에이전트가 발견하고 호출할 수 있는 이산적이고 기계 판독 가능한 능력(이름, 입력 스키마, 출력 스키마, 권한 검사, 실행 콜백)을 등록하기 위한 코어 API입니다. 최근에 도입되었으므로 사용 전에 최소 WordPress 버전과 정확한 함수 이름을 개발자 문서에서 확인하세요 ("Abilities API" 검색). PRD에 에이전트가 호출할 수 있는 함수가 필요한 경우에만 사용하세요; 일반적인 클라이언트-서버 호출에는 일반 REST가 적합합니다.
능력을 등록할 때:
- 먼저 카테고리를 등록하고, 그 다음 능력을 문서화된 훅에 등록하세요.
- 입력 및 출력에 JSON 스키마를 제공하고, 실제 기능(capability)을 확인하는
permission_callback을 제공하세요. - 안전 주석을 정직하게 설정하세요: 읽기 전용 능력은 쓰기를 해서는 안 되며, 파괴적 능력은 플래그를 지정해야 합니다. 읽기 전용으로 주석이 달린 콜백이 쓰기를 수행하는 것은 결함이며,
fswp-reviewer는 이를 결함으로 처리합니다. - 원격으로 호출 가능해야 하는 것만 REST로 노출하세요.
감사 및 검증 절차: references/abilities.md.
기존 엔드포인트 중 어떤 것이 능력이 되어야 하는지 제안하려면 각 경로의 메서드, 현재 권한 검사, 부작용, 제안된 주석을 나열하세요; 승인될 때까지 아무것도 등록하지 마세요.