What's Changed: v2 Beta 1 Edit Page

This document is a summary of what we’ve changed in the REST API between versions 1 and 2. The key changes to the API are listed below, along with an example of migrating an endpoint to version 2.

Important note: Beta 1 does not guarantee forwards compatibility with future betas. While we believe the API is now stable enough for public testing, we may continue to break the API in the future as we improve it further. Only use the API in development, and do not use version 2 in production environments.

As always, we’d love your feedback on what we’re doing right, or what we’re doing wrong. If there’s changes in here that make you think “what were they thinking”, let us know. If something’s missing that needs further changing, then we’d also love to know that. :)

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.