As we have seen previosly the REST API is an essential tool for creating dynamic and interactive web applications using WordPress. The WP_REST_Controller class is a fundamental part of this API, providing a structured way to handle RESTful routes and endpoints.

What is WP_REST_Controller?

The WP_REST_Controller class is an abstract class which provides basic structure for creating REST API endpoints. It includes methods for registering and handling requests and responses. By extending this class we can create custom endpoints.

Extending WP_REST_Controller

First we need to create a new class that will inherit WP_REST_Controller class, this class will define routes and handle the requests at custom end points.

Defining Custom controller class

<?php
use WP_REST_Controller;
use WP_REST_Request;
use WP_REST_Response;
use WP_REST_Server;

class Custom_REST_Controller extends WP_REST_Controller {
    public function __construct() {
        $this->namespace = 'namespace/v1';
        $this->rest_base = 'our-endpoint';

        add_action( 'rest_api_init', array( $this, 'register_routes' ) );
    }

    public function register_routes() {
        register_rest_route(
            $this->namespace,
            '/' . $this->rest_base,
            array(
                array(
                    'methods'             => WP_REST_Server::READABLE,
                    'callback'            => array( $this, 'get_items' ),
                    'permission_callback' => array( $this, 'get_items_permissions_check' ),
                    'args'                => $this->get_collection_params(),
                ),
                array(
                    'methods'             => WP_REST_Server::CREATABLE,
                    'callback'            => array( $this, 'create_item' ),
                    'permission_callback' => array( $this, 'create_item_permissions_check' ),
                    'args'                => $this->get_endpoint_args_for_item_schema( WP_REST_Server::CREATABLE ),
                ),
                'schema' => array( $this, 'get_public_item_schema' ),
            )
        );

        register_rest_route(
            $this->namespace,
            '/' . $this->rest_base . '/(?P<id>[\d]+)',
            array(
                'args'   => array(
                    'id' => array(
                        'type' => 'integer',
                    ),
                ),
                array(
                    'methods'             => WP_REST_Server::READABLE,
                    'callback'            => array( $this, 'get_item' ),
                    'permission_callback' => array( $this, 'get_item_permissions_check' ),
                    'args'                => array(
                        'context' => $this->get_context_param( array( 'default' => 'view' ) ),
                    ),
                ),
                array(
                    'methods'             => WP_REST_Server::EDITABLE,
                    'callback'            => array( $this, 'update_item' ),
                    'permission_callback' => array( $this, 'update_item_permissions_check' ),
                    'args'                => $this->get_endpoint_args_for_item_schema( WP_REST_Server::EDITABLE ),
                ),
                array(
                    'methods'             => WP_REST_Server::DELETABLE,
                    'callback'            => array( $this, 'delete_item' ),
                    'permission_callback' => array( $this, 'delete_item_permissions_check' ),
                ),
                'schema' => array( $this, 'get_public_item_schema' ),
            )
        );
    }

    public function get_items( WP_REST_Request $request ) {
        // Implement logic to retrieve items
    }

    public function get_item( WP_REST_Request $request ) {
        // Implement logic to retrieve a single item
    }

    public function create_item( WP_REST_Request $request ) {
        // Implement logic to create a new item
    }

    public function update_item( WP_REST_Request $request ) {
        // Implement logic to update an item
    }

    public function delete_item( WP_REST_Request $request ) {
        // Implement logic to delete an item
    }

    public function get_items_permissions_check( WP_REST_Request $request ) {
        // Implement permission check logic
    }

    public function get_item_permissions_check( WP_REST_Request $request ) {
        // Implement permission check logic
    }

    public function create_item_permissions_check( WP_REST_Request $request ) {
        // Implement permission check logic
    }

    public function update_item_permissions_check( WP_REST_Request $request ) {
        // Implement permission check logic
    }

    public function delete_item_permissions_check( WP_REST_Request $request ) {
        // Implement permission check logic
    }

    public function prepare_item_for_response( $item, WP_REST_Request $request ) {
        // Implement logic to prepare the item for the response
    }

    public function get_collection_params() {
        // Implement logic to get the collection parameters
    }
}

We need to register routes this will be done by implementing the register_routes() function. This function will hold all the routes and their parameters.

Implementing the methods

After defining the structure of our routes we need to make sure all our callbacks are defined.

Eg— Sample function definition of get_items and create_item.

public function get_items( WP_REST_Request $request ) {
    $args = array(
        'post_type'      => 'custom-post-type',
        'posts_per_page' => $request['per_page'],
        'paged'          => $request['page'],
        'orderby'        => $request['orderby'],
        'order'          => $request['order'],
    );

    if ( ! empty( $request['search'] ) ) {
        $args['s'] = $request['search'];
    }

    $query = new WP_Query( $args );
    $posts = array();

    if ( $query->have_posts() ) {
        while ( $query->have_posts() ) {
            $query->the_post();
            $data    = $this->prepare_item_for_response( get_post(), $request );
            $posts[] = $this->prepare_response_for_collection( $data );
        }
        wp_reset_postdata();
    }

    $response = rest_ensure_response( $posts );
    return $response;
}

public function create_item( $request ) {
    $title = sanitize_text_field( $request['title'] );
    $content = wp_kses_post( $request['content'] );
    $status = sanitize_text_field( $request['status'] );

    $new_post = array(
        'post_type' => 'custom-post-type',
        'post_title' => $title,
        'post_content' => $content,
        'post_status' => $status,
        'post_author' => get_current_user_id(),
    );

    $post_id = wp_insert_post( $new_post );

    if ( is_wp_error( $post_id ) ) {
        return $post_id;
    }

    return rest_ensure_response( $this->prepare_item_for_response( get_post( $post_id ), $request ) );
}

Implementing Permission callbacks

The permission_callback is used to ensure the correct permissions are in place before any data is retrieved or modified on every request.

public function create_item_permissions_check( $request ) {
    return is_user_logged_in() && current_user_can( 'publish_posts' );
}

Preparing the Response

public function prepare_item_for_response( $post, $request ) {
    return array(
        'id' => $post->ID,
        'title' => $post->post_title,
        'content' => $post->post_content,
    );
}

Registering the Routes

The last thing we need to do before our routes are available is to register them using the rest_api_init hook.

add_action( 'rest_api_init', function() {
    $controller = new Custom_REST_Controller();
    $controller->register_routes();
} );

Conclusion

The WP_Rest_Controller class provides a solid foundation for building custom REST API endpoints in WordPress. By extending this class, we can define custom routes and handle CRUD operations.