WordpPressで register_rest_route を使った独自のエンドポイントを作成する方法のまとめ。
環境
- WordPress 5.4.4
- PHP 7.2.9
register_rest_route 関数の説明
WordPressでは register_rest_route で REST API の作成ができます。
RESTful APIとは、Webシステムを外部から利用するためのプログラムの呼び出し規約（API）の種類の一つで、「REST」（レスト）と呼ばれる設計原則に従って策定されたもの。RESTそのものは適用範囲の広い抽象的なモデルだが、一般的にはRESTの考え方をWeb APIに適用したものをRESTful APIと呼んでいる。
IT用語辞典：RESTful API 【REST API】
公式ドキュメントより register_rest_route は下記のように定義されています、
register_rest_route( string $namespace, string $route, array $args = array(), bool $override = false )
register_rest_route の詳細は下記のサイトに。
オプションについて次にまとめます。
$namespace
(文字列) (必須) コアプレフィックスの後の最初のURLセグメント。パッケージ/プラグインに固有のものでなければなりません。
$route
(文字列) (必須) 追加するルートのベースURL。
$args
(array) （オプショナル） エンドポイントに対するオプションの配列か、 複数のメソッド群に対する配列のいずれか。
$override
(bool) (オプション) ルートがすでに存在する場合、それをオーバーライドするか。True はオーバーライドし、False はマージします (重複するキーが存在する場合は新しいオーバーライドを使用します)。
ドキュメントを読んでもよくわからない場合もあるので次の具体例をみていきましょう。
GET
まずはGETのエンドポイントの追加。
add_action('rest_api_init', function() {
register_rest_route( 'myapi/v1', '/test1', [
'methods' => 'GET',
'callback' => 'func_test1',
'permission_callback' => function() { return true; }
]);
});
function func_test1() {
// ここに何らかの処理
$return['title']='title';
$return['body']='body';
return new WP_REST_Response( $return, 200 );
}REST APIを作成する場合には rest_api_init というアクションフックで register_rest_route の登録を行います。
上の例の場合、「<your site url>/wp-json/myapi/v1/test1」が新しいエンドポイントとして追加されます。
エンドポイントは(デフォルトでは) /wp-json/がルートとなります。
第三引数のcallbackで指定した関数がAPIアクセス時に呼び出されます。
次のコードは curl でGETした例です。
$ curl <your site url>/wp-json/myapi/v1/test1
{"title":"title","body":"body"}func_test1() 処理内容はWP_REST_Response関数を使って配列をJSONの形式に変換して返却します。
permission_callback WP5.5から必須に
上のコードでは return true; とし公開APIとして誰でもアクセスができるようにしていましたが、APIごとに権限でアクセス制限を行いたい場合は次のように実装します。
add_action('rest_api_init', function() {
register_rest_route( 'myapi/v1', '/test1', [
'methods' => 'GET',
'callback' => 'func_test1',
'permission_callback' => 'rest_permission'
]);
});
//APIの権限をチェックする関数
function rest_permission(){
return current_user_can('publish_posts');
}
function func_test1() {
// ここに何らかの処理
$return['title']='title';
$return['body']='body';
return new WP_REST_Response( $return, 200 );
}このようにした場合 publish_postsの権限を持ったユーザーのみAPIへのアクセスができます。
GET パラメータ有
add_action('rest_api_init', function() {
register_rest_route( 'myapi/v1', '/test2/(?P<id>[a-zA-Z0-9-]+)', array(
'methods' => 'GET',
'callback' => 'func_test2',
'permission_callback' => function() { return true; }
));
});
function func_test2($date) {
// ここに何らかの処理
$id = $date['id'];
$return['id'] = $id;
$return['title']='title';
$return['body']='body';
return new WP_REST_Response( $return, 200 );
}URLからパラメータを渡したい場合は上のように正規表現で追加します。
$ curl <your site url>/wp-json/myapi/v1/test2/id123
{"id":"id123","title":"title","body":"body"}POST
最後にPOSTメソッドのエンドポイントの追加。
add_action('rest_api_init', function() {
register_rest_route( 'myapi/v1', '/test3', array(
'methods' => 'POST',
'callback' => 'func_test3',
'permission_callback' => function() { return true; }
));
});
function func_test3($request) {
// ここに何らかの処理
$args = json_decode($request->get_body(),true);
$return['Name']=$args['Name'];
$return['Age']=$args['Age'];
return new WP_REST_Response( $return, 200 );
}リクエスト時に投げられた JSON データを json_decode($request->get_body(),true) で受け取ります。
curl で POST する際は次のように書くことでリクエストを投げることができます。
$ curl -X POST -H "Content-Type: application/json" -d '{"Name":"sibainu", "Age":"2"}' <your site url>/wp-json/myapi/v1/test3
{"Name":"sibainu","Age":"2"}おわりに
今回の例ではコールバック関数内で具体的な処理はせずにデータの受け取り方やデータの戻し方の基本を中心にまとめてみました。
これまでは admin-ajax などを使う場面が多かったですが、REST形式だとレスポンス速度が優秀なため積極的に取り入れていこうと思います。
