[워드프레스] 25. REST : REST API 커스텀 엔드포인트 만드는 법

(워드프레스 해부 ㉕) REST

워드프레스는 /wp-json/ 아래로 REST API를 열어둔다. 글·미디어·설정을 HTTP로 읽고 쓸 수 있다. 사실 나는 이 시리즈 36편 전체를 REST API로 발행하고 편집했다 — 관리자 화면을 거의 안 열고, /wp-json/wp/v2/posts에 요청을 보내 글을 만들고 예약했다. 그만큼 강력하다.

내 전용 엔드포인트도 만들 수 있다. register_rest_route()를 rest_api_init 훅에 걸면 된다.

직접 해보기

add_action( 'rest_api_init', function() {
    register_rest_route( 'myplugin/v1', '/hello', array(
        'methods'  => 'GET',
        'callback' => function( $request ) {
            $name = sanitize_text_field( $request->get_param( 'name' ) ?: '세계' );
            return array( 'message' => "안녕, {$name}!" );
        },
        'permission_callback' => '__return_true',  // 공개(실무선 권한 확인)
    ) );
} );
// 호출:  /wp-json/myplugin/v1/hello?name=코즈모

permission_callback이 핵심이다. 이걸 __return_true로 열어두면 누구나 접근한다. 쓰기·민감 데이터라면 반드시 current_user_can()으로 권한(11편)을 확인해야 한다.

✅ 확인 — 브라우저나 curl로 /wp-json/myplugin/v1/hello?name=코즈모를 열었을 때 {"message":"안녕, 코즈모!"} JSON이 나오면 성공. 이게 워드프레스를 “헤드리스”로 다루는 출발점이다.

커스텀 엔드포인트 한 벌

기본 /wp/v2 말고 내 전용 경로를 열려면 register_rest_route를 쓴다. 등록은 init이 아니라 rest_api_init 훅 안에서 해야 한다. 이걸 놓치면 경로가 안 잡힌다.

add_action( 'rest_api_init', function () {
    register_rest_route( 'cozlab/v1', '/hello/(?P<name>[a-z가-힣]+)', array(
        'methods'  => 'GET',
        'callback' => function ( $req ) {
            // return한 값이 그대로 JSON 응답이 된다
            return array( 'message' => '안녕하세요, ' . $req['name'] . '님' );
        },
        'permission_callback' => '__return_true',   // 공개 (아래 참고)
    ) );
} );

경로의 (?P<name>...)가 URL의 일부를 파라미터로 잡아 $req['name']으로 넘겨준다. namespace(cozlab/v1)는 다른 플러그인과 안 겹치게 자기만의 이름으로 짓는다.

권한은 permission_callback에서 막는다

가장 중요한데 자주 빠뜨리는 게 permission_callback이다. 이걸 __return_true로 열어두면 누구나 그 엔드포인트를 부를 수 있다. 민감한 데이터나 쓰기 작업이면 반드시 여기서 권한을 검사한다.

'permission_callback' => function () {
    return current_user_can( 'edit_posts' );   // 편집 권한 있는 사용자만
},

입력은 args로 검증·정제한다

파라미터의 타입·필수 여부·검증·정제를 args로 선언해두면, 콜백에 도달하기 전에 워드프레스가 걸러준다. 19편의 sanitize가 여기서도 그대로 적용된다.

'args' => array(
    'name' => array(
        'required'          => true,
        'sanitize_callback' => 'sanitize_text_field',
        'validate_callback' => function ( $v ) { return is_string( $v ); },
    ),
),

호출과 흔히 만나는 오류

만든 엔드포인트는 /wp-json/cozlab/v1/hello/코즈모로 부른다. rest_no_route 오류가 뜨면 네임스페이스·경로 오타이거나 rest_api_init이 아닌 곳에서 등록한 것이다. 쓰기(POST) 요청은 인증이 필요하다 — 서버 간이면 애플리케이션 비밀번호, 브라우저 JS면 nonce를 함께 보내야 하고, 다른 도메인에서 부르면 CORS까지 챙겨야 한다.

기본 엔드포인트 vs 커스텀, 언제 무엇을

글·미디어·설정 같은 표준 데이터는 기본 /wp/v2 엔드포인트로 충분하다 — 내가 이 시리즈 36편을 발행·예약한 것도 전부 이 기본 엔드포인트였다. 커스텀 엔드포인트는 ‘내 도메인 로직’을 노출할 때 만든다. 특정 계산 결과, 외부 서비스 연동, 헤드리스 프런트가 쓸 맞춤 데이터처럼, 기본 API로는 표현이 안 되는 걸 열 때다.

확장 모듈의 마지막은 편집 화면에 입력칸을 더하는 메타박스다. 지금까지 배운 게 다 모인다.

자주 묻는 질문 (FAQ)

커스텀 REST 엔드포인트는 어떻게 만드나요?

register_rest_route로 경로·메서드·콜백·권한 검사를 등록합니다. /wp-json/ 아래에 노출됩니다.

REST 엔드포인트에 권한을 어떻게 거나요?

permission_callback에서 현재 사용자의 권한을 검사합니다. 공개 여부를 여기서 통제합니다.