Wordpress 上で API を新たに定義する

WordPress で API を定義するには WordPress の REST API の仕組みに乗れる register_rest_route というのを使う。 メソッドも処理もその他差し込み動作も指定し放題。

テンプレート下に php おいて$_POST でできます！はまちがい。これだと WordPress がもってる様々な恩恵に授かれない。

ちなみに環境によっては WordPress のプラグインで API を指定して無効にしたりするものが入っているかもしれないが register_rest_route した API はちゃんと出てくる、はず…。

さてこの register_rest_route の公式説明をみると、プラグイン名で名前をつけろ、とある。 register_rest_route() | Function | WordPress Developer Resources

特に配布するようなものでないとか規模が小さいとかなら api/v1 とかつければいいと思う。 機能や振る舞いに合わせてちゃんと名付けするのがいいとは思うけど。

というわけで基本形の使い方はこういう感じ。 クロージャーでシュッと書けばいいし、別にラップするクラスを作るなどしてよしなにしてもいいのではと思った。

add_action('rest_api_init', function() {
    register_rest_route( 'myapi/v1', '/foo', [
        'methods' => 'POST',
        'callback' => function(WP_REST_Request $req) {
            $message = $req['message'];

            $response = new WP_REST_Response;
            $response->set_status(200);
            $response->set_data([
                'result' => 'success',
                'message' => $message,
            ]);
            return $response;
        },
    ]);
});

クラスで簡単にラップする、例えばこういう感じ。やり方は無限。

class PostAPI
{
    private $namespace;

    public function __construct(string $namespace)
    {
        $this->namespace = $namespace;
    }

    public function register(string $endpoint, \Closure $handler)
    {
        register_rest_route(
            $this->namespace,
            $endpoint,
            [
                'methods' => 'POST',
                'callback' => $handler,
            ]
        );
    }
}

add_action('rest_api_init', function() {
    $api = new PostAPI('myapi/v2');
    $api->register('/foo', function(WP_REST_Request $req) {
        $message = $req['message'];

        $response = new WP_REST_Response;
        $response->set_status(200);
        $response->set_data([
            'result' => 'success',
            'message' => $message,
        ]);
        return $response;
    });
});

リクエストパラメータを受け取るには、$req が WP_REST_Request になっていて、これを使う。 WP_REST_Request | Class | WordPress Developer Resources

ArrayAccess の機能を持っていて、パラメータをよしなに取得できるようになっていてお手軽度が高い。

そしてレスポンスは WP_REST_Response を使う。 これもお手軽度が高く、勝手に json フォーマットに変換してくれたりする。 WP_REST_Response | Class | WordPress Developer Resources

こうして作った API は、とくに認証や制限を書けていないならすぐにでも curl や Javascript での Ajax から呼び出すことができる。

$ curl -X POST -H 'Content-Type:application/json' '{{WordPress url}}/wp-json/myapi/v1/foo?message=its_query'
{"result":"success","message":"its_query"}

$ curl -X POST -H 'Content-Type:application/json' -d '{"message":"its json"}' '{{WordPress url}}/wp-json/myapi/v1/foo'
{"result":"success","message":"its json"}

こういう具合。