WP REST API V2にてカスタムエンドポイントを追加するまとめ

カスタムエンドポイントの作り方全般をまとめてみた。

環境など

  • PHP 5.6
  • WordPress ver.4.5.3
    • WP REST API ver.2.0-beta13.1
  • ドメイン : http://wprest.local

GET

まずは基本的な追加方法としてGETメソッドのエンドポイントを追加する。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

add_action( 'rest_api_init', 'add_custom_endpoint' );
function add_custom_endpoint() {
  register_rest_route( 'custom/v0', '/show', array(
      'methods' => 'GET',
      'callback' => 'create_item'
  ) );
}
function show_item(){
  //何かしらの処理
  $data = ['apple'=>'りんご', 'peach'=>'もも', 'pear'=>'なし'];

  $response = new WP_REST_Response($data);
  $response->set_status(200);
  $domain = (empty($_SERVER["HTTPS"]) ? "http://" : "https://") . $_SERVER["HTTP_HOST"];
  $response->header( 'Location', $domain );
  return $response;
}

rest_api_initのフックでREST APIが初期化されたタイミングで追加する。
呼びだされたadd_custom_endpoint関数内でAPIのエンドポイントを追加している。
エンドポイントを追加するには、register_rest_routeを利用する。

  • 第一引数 : 名前空間
  • 第二引数 : エンドポイント
  • 第三引数 : メソッドなどの設定配列

第一引数と第二引数を合わせたものがエンドポイントとなる。
エンドポイントは(デフォルトでは) /wp-json/がルートとなるのでこの指定はそれ以下の分、となる。

なので、このエンドポイントへのアクセスは以下のURLのようになる。
http://wprest.local/wp-json/custom/v0/show

第三引数のcallbackで指定した関数がAPIアクセス時に呼び出される。
返却する内容は実はなんでも構わないが、WP_REST_Responseクラスを利用することでヘッダーなどの設定が出来るよう。
ここでは、ステータス200、ヘッダーにドメインをロケーションで追加、などしている。

返ってくる内容は以下。

1
2
3
4
5

{
  "apple": "りんご",
  "peach": "もも",
  "pear": "なし"
}

パラメータの追加

REST APIらしく、URLにIDなどのパラメータを含める事ができる。
register_rest_routeでエンドポイントを指定する時に以下のようにする。

1
2
3
4

register_rest_route( 'custom/v0', '/show/(?P<id>\d+)', array(
  'methods' => 'GET',
  'callback' => 'show_item_id'
) );

受け取る際は、コールバックの関数内で以下のようにする。

1
2
3
4
5

function show_item_id($data){
  $posts = get_posts( array(
      'author' => $data['id'],
  ) );
//(後略)

メソッドの指定方法

メソッドの指定方法はGETやPOSTなど文字列での指定も可能だが、WP_REST_Serverクラスを指定して複数いっぺんに指定が出来たりもする。

1
2
3
4

register_rest_route( 'custom/v0', '/show', array(
  'methods' => WP_REST_Server::READABLE,
  'callback' => 'show_item'
) );
  • READABLE = ‘GET’
  • CREATABLE = ‘POST’
  • EDITABLE = ‘POST, PUT, PATCH’
  • DELETABLE = ‘DELETE’
  • ALLMETHODS = ‘GET, POST, PUT, PATCH, DELETE’

エラーの追加

指定されたIDの投稿がないなど、エラーを返したい場合は以下のようにする。
(404エラーの場合の例）

1
2
3
4
5

function show_item_id($data){
  if($data['id'] == 0){
      return new WP_Error( 'awesome_no_author', 'Invalid author', array( 'status' => 404 ) );
  }
}

/custom/v0/show/0でアクセスすると以下のように返ってくる。

1
2
3
4
5
6
7

{
  code: "awesome_no_author",
  message: "Invalid author",
  data: {
      status: 404
  }
}

POST

ポストでの送信、データ取得は以下。ほぼ、GETの時と変わらない。
送られたデータはどうやって取得するのかすごく悩んだのだが、単純に$_POSTで取得、でよかった。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

add_action( 'rest_api_init', 'add_custom_endpoint' );
function add_custom_endpoint() {
  register_rest_route( 'custom/v0', '/create', array(
      'methods' => 'POST',
      'callback' => 'create_item'
  ) );
}

function create_item() {
  $data = $_POST;
  $response = new WP_REST_Response( $data );
  $response->set_status( 201 );
  $domain = (empty($_SERVER["HTTPS"]) ? "http://" : "https://") . $_SERVER["HTTP_HOST"];
  $response->header( 'Location', $domain );

  return $response;
}

送った内容を表示させているだけ、の内容。
bodyで、id=2, body=testの２つを送ってみると、返ってくる値は以下。

1
2
3
4

{
  "id": "2",
  "body": "test"
}

権限

特にPOSTなどは実行するには認証を必要としたい場合が多いと思う。
そういう時には、実行前に権限をチェックする関数を呼び出すものとして、permission_callbackが用意されている。
register_rest_routeの第三引数の中で以下のように指定する。

1
2
3
4
5

register_rest_route( 'custom/v0', '/create', array(
  'methods' => 'POST',
  'permission_callback' => 'create_permissions_check',
  'callback' => 'create_item'
) );

この呼びだされた関数で、trueを返すと通り、falseを返すとエラーとなる。
エラーは以下のように返却される。

1
2
3
4
5
6
7

{
  "code": "rest_forbidden",
  "message": "この操作を行う権限がありません。",
  "data": {
    "status": 403
  }
}

この権現の確認は、current_user_can関数で行う。

1
2
3

function create_permissions_check(){
  return current_user_can('publish_posts');
}

OAuthやアプリケーションパスワードを使った認証部分はこの手前で完了しているため、実際に接続しに来たユーザーの権限をここでチェックしてやるだけで良い。
権限は以下を参考に。

参考: current_user_can:WordPress私的マニュアル

参考

wordpress
   このエントリーをはてなブックマークに追加