What's Changed: v2 Beta 1 Edit Page

このドキュメントでは、REST APIのバージョン1と2の更新情報の概要について説明します。主な変更点は以下のとおりです。さらにバージョン1から2へ移行する際のサンプルコードも用意しています。

重要: ベータ1は、将来のバージョンで互換性が保障されているわけではありません。公にテストを行うには十分な信頼性があると考えていますが、さらに改善するために互換性がなくなるかもしれません。バージョン2は、本番環境では使用しないで開発環境においてのみ使用してください。

これまで通り、私たちが正しいことをするにも、誤ったことをするにも、みなさんのフィードバックを歓迎します。もし「彼らは何を考えてるんだろう?」と思うようなことがあれば知らせてください。もし何か見逃していることがあれば、ぜひそれを知りたいと思っています。

Key Changes

Internals

External API

Future Changes

We have the following on our mind for further evolution of the API as we progress through to beta 2 and beyond:

Migrating endpoints from v1 to v2

Migrating endpoints from version 1 code to version 2 is pretty simple, and the easiest way to see this is by example. Let's take an example API:

<?php
add_filter( 'json_endpoints', 'tsla_register_routes' );

function tsla_register_routes( $routes ) {
    $routes[ '/tsla/honk_horn' ] = array( 'tsla_add_horn_honks', WP_JSON_Server::READABLE );
    return $routes;
}

function tsla_add_horn_honks( $honks = 1 ) {
    if ( ! is_numeric( $honks ) ) {
        return new WP_Error( 'tsla_honks_invalid', 'Honks must be a number', array( 'status' => 400 ) );
    }
    $count = get_option( 'wc-heartbeat-honk', 0 );
    update_option( 'wc-heartbeat-honk', $count + $honks );
    $response = new WP_JSON_Response( array( 'result' => true ) );
    $response->header( 'X-Prev-Honks', $count );
    return $response;
}

This is a nice simple API for us to deal with, but has a bit of complexity: it takes (optional) arguments, has error handling, and also has some custom headers. There are a few key changes we need to make here:

Here's what the new API looks like:

<?php
add_filter( 'rest_api_init', 'tsla_register_routes' );

function tsla_register_routes( $routes ) {
    register_rest_route( 'tsla', '/honk_horn', array(
        'callback' => 'tsla_add_horn_honks',
        'methods'  => WP_REST_Server::READABLE,
        'args'     => array(
            'honks' => array(
                'required'          => false,
                'validate_callback' => 'is_numeric',
            ),
        )
    ) );
}

function tsla_add_horn_honks( WP_REST_Request $request ) {
    $honks = $request['honks'];
    $count = get_option( 'wc-heartbeat-honk', 0 );
    update_option( 'wc-heartbeat-honk', $count + $honks );
    $response = new WP_REST_Response( array( 'result' => true ) );
    $response->header( 'X-Prev-Honks', $count );
    return $response;
}

You'll notice that a lot of this looks pretty much the same! We've moved our validation check out, and renamed a few things, but otherwise our callback is mostly the same. The route registration has expanded to use the function for registration instead.