Whenever I embark on a new piece of technology or infrastructure, my favourite approach is to build a quick Proof of Concept. For me this lets me know that I have understood and correctly interpreted the basics.

WordPress REST Concepts

Quick read of the WordPress REST API handbook and it details the five basic concepts

1. Routes & Endpoints
2. Requests
3. Responses
4. Schema
5. Controller Classes

Routes & Endpoints

Routes and Endpoints are basically the URIs (Routes) and associated functions (Endpoints) that form the REST service. The last sentences is not strictly accurate though, because an Endpoint is not just the function that processes the request, it is actually the Route & the function.

Requests

This is the list of requests that the REST serive can handle. Types of REST requests (which WordPress referes to as Methods) are:

• Http GET – Read
• Http POST – Create
• Http PUSH – Update / Replace / Modify
• Http DELETE – Delete

Responses

The data returned by the REST service, together with Meta data describing the response (such Header=201/OK or 404/Not Found)

Schema

Defines the JSON schema for the data. In my case I have a DVD object, defined in PHP as follows:

function q5_dvd_get_schema() {
     $schema = array(
     '$schema'      => 'http://json-schema.org/2019-09/schema#',
     'title'         => 'dvd',
     'type'          => 'object',
     'properties'    => array(
         'title'     =>      array(
             'description'   => esc_html__('Tilte of Film'),
             'type'          => 'string'
             ),
         'studio'    =>      array(
             'description'   => esc_html__('Studio that released the film'),
             'type'          => 'string'
             ),
         'released'  =>      array(
             'description'   => esc_html__('Year film was released (not necessarily same as DVD release'),
             'type'          => 'integer'
             ),
         'version'   =>      array(
             'description'   => esc_html__('DVD version - SD, HD, Blu-ray'),
             'type'          => 'string'
             ),
         'rating'    =>      array(
             'description'   => esc_html__('Movie guidance rating - G, PG, PG-13, R, NC-17'),
             'type'          => 'string'
             ),
         'genres'    =>      array(
             'description'   => esc_html__('List of one or more genre for the movie'),
             'type'          => 'array',
             'items'         => array(
                 'description'   => esc_html__('Genre - Extensible list of genres'),
                 'type'          => 'string'
                 )
             ),
         'barcode'   =>          array(
             'description'       => esc_html__('13 numeric code'),
             'type'              => 'integer',
             'minlength'         => 13,
             'maxlength'         => 13
             ),
         'description'   =>      array(
             'description'       => esc_html__('Brief deswcription of movie'),
             'type'              => 'string'
             ),
         'cast'          =>      array(
             'description'       => esc_html__('List of main stars'),
             'type'              => 'array',
             'items'             => array(
                 'type'              => 'object',
                 'properties'        => array(
                     'first_name'        =>array(
                         'description'   => esc_html__('First name'),
                         'type'          => 'string'
                         ),
                     'last_name'     =>array(
                         'description'   => esc_html__('Last name'),
                         'type'          => 'string'
                         )
                     )
                 )
             )
         )
     );
     return $schema;
 }

The schema for this class is as follows:

 function q5_dvd_get_schema() {
     $schema = array(
     '$schema'      => 'http://json-schema.org/2019-09/schema#',
     'title'         => 'dvd',
     'type'          => 'object',
     'properties'    => array(
         'title'     =>      array(
             'description'   => esc_html__('Tilte of Film'),
             'type'          => 'string'
             ),
         'studio'    =>      array(
             'description'   => esc_html__('Studio that released the film'),
             'type'          => 'string'
             ),
         'released'  =>      array(
             'description'   => esc_html__('Year film was released (not necessarily same as DVD release'),
             'type'          => 'integer'
             ),
         'version'   =>      array(
             'description'   => esc_html__('DVD version - SD, HD, Blu-ray'),
             'type'          => 'string'
             ),
         'rating'    =>      array(
             'description'   => esc_html__('Movie guidance rating - G, PG, PG-13, R, NC-17'),
             'type'          => 'string'
             ),
         'genres'    =>      array(
             'description'   => esc_html__('List of one or more genre for the movie'),
             'type'          => 'array',
             'items'         => array(
                 'description'   => esc_html__('Genre - Extensible list of genres'),
                 'type'          => 'string'
                 )
             ),
         'barcode'   =>          array(
             'description'       => esc_html__('13 numeric code'),
             'type'              => 'integer',
             'minlength'         => 13,
             'maxlength'         => 13
             ),
         'description'   =>      array(
             'description'       => esc_html__('Brief deswcription of movie'),
             'type'              => 'string'
             ),
         'cast'          =>      array(
             'description'       => esc_html__('List of main stars'),
             'type'              => 'array',
             'items'             => array(
                 'type'              => 'object',
                 'properties'        => array(
                     'first_name'        =>array(
                         'description'   => esc_html__('First name'),
                         'type'          => 'string'
                         ),
                     'last_name'     =>array(
                         'description'   => esc_html__('Last name'),
                         'type'          => 'string'
                         )
                     )
                 )
             )
         )
     );
     return $schema;
 }

Controller Classes

The Request types (Push, Get, Pull, Delete) are equivalent to D/B CRUD actions. A Controller Class is used to contain all the logic for a given route. (i.e It will contain all the Endpoint methods, and other supporting functions.)

Two very important advantages to using Controller Classes.

1. Using Classes helps eliminate any Namespace issues. It is relatively easy to prefix all functions with the class name
2. You can sub-class from the abstract WP_REST_Controller class, which provides a number of useful functions, and again assists in ensuring that you follow best practice.

Note: You do no t need to structure your code to use Controller Classes, nor do you need to define Schemas, but doing so will assist in keeping the REST compliant with best practices.