[Basics] REST Ajax

REST API & Ajax

The framework creates several REST API endpoints and also helps the plugin/theme to create custom endpoints. In addition, the base class has several methods that make it easier to handle Ajax requests.

REST API router

Many endpoints require a router parameter to be passed. This is a unique key associated with the plugin/theme. It is thanks to the presence of router that the method that processes the request selects the plugin/theme that will process the given request. This is due to the fact that REST API endpoints are the same for all active plugins/themes using this framework, and without specifying router it is impossible to determine which plugin calls the endpoint.

The key for router itself and its link to the plugin/theme is automatically generated. Also, most of the framework's functions for working with the REST API automatically add router in requests. Only in some cases will you have to pass router manually.

In JS code, router is passed as part of JSON data.

Zukit REST API endpoints

The namespace for Zukit endpoints is zukit/v1. The framework currently supports the following endpoints:

• action (POST)

  Serves to perform actions from the Settings Page

  Arguments: router(string), key(string)

---

• option (GET)

  Serves to request the value of plugin/theme option via Ajax

  Arguments: router(string), key(string) - can contain path (dots separated keys)

---

• options (POST)

  Serves to set options for requested keys via Ajax

  Arguments: router(string), keys(array) - each key can contain path (dots separated keys), values(array) - key/value pairs

---

• zudata (GET)

  Serves to get some framework data via Ajax (e.g. loaders SVG)

  Arguments: key(string)

  ❗ The processing of a zudata request can be extended in the plugin/theme.
  See below for details.

---

• cuget (GET)

  Serves to get CUSTOM data via Ajax

  Arguments: key(string)

  ❗ cuget endpoint provides an alternative to creating custom endpoints in the plugin/theme.
  See below for details.

---

• cuset (POST)

  Serves to set CUSTOM data via Ajax

  Arguments: key(string), keys(array) - each key can contain path (dots separated keys), values(array) - key/value pairs

  ❗ cuset endpoint provides an alternative to creating custom endpoints in the plugin/theme.
  See below for details.

---

Extending zudata

The processing of a zudata request can be extended by the plugin/theme. To do this, you need to override the extend_zudata method, which has two arguments: $key and $params. If your plugin/theme handles a request with this key, then the handler should return a non-null value. The $params array can contain additional request parameters.

The framework contains several custom hooks for getting zudata in JS code (see more in the REST API requests).

// return array of folders (e.g. your plugin supports folder management)
protected function extend_zudata($key, $params) {
    $result = null;
    if($key === 'folders') {
        $folder_id = $params['folderId'] ?? null;
        $result = empty($folder_id) ? $this->get_folders() : $this->get_folder_by_id($folder_id);
    }
    return $result;
}

Custom REST API endpoints (simple way)

Instead of creating your custom endpoints, you can use special cuget and cuset endpoints. To do this, you need to override the get_custom_value and set_custom_value methods (or only one of them if you do not need, for example, getting data through the REST API). Both methods receive $request_id as the first argument, which will allow you to identify your request - you must pass this request_id when accessing the endpoint from the JS code (see more in the REST API requests). If your plugin/theme handles a request with this key, then the handler should return a non-null value.

The get_custom_value method has the second argument $params - is an array which can contain additional request parameters. The set_custom_value method has two additional arguments ($keys and $values) that contain the keys of the values to be updated and the values themselves.

// example of using REST API to update statistics for 'post_id'
protected function set_custom_value($request_id, $keys, $values) {
    if($request_id !== 'my_stats') return null;

    $post_id = $values['id'];
    $value = $values['value'];

    if(empty($post_id)) return false;

    // Update statistics
    $this->update_stats($post_id, $value);
    return true;
}

Custom REST API endpoints (more difficult way)

You need to override the api_routes method in which to return an array describing your REST API routes including arguments, permission, callback function, and more.

You also need to implement the methods responsible for handling the request, as well as sanitize the incoming arguments. You can use the helpers that come with WordPress or the framework (see below).

❗ Please note that when defining a callback function, you only need to specify the function name ('my_request') for the request processing, not the array [$this, 'my_request']. The framework assumes that the function for handling the request is a method of your class and the reference to $this will be added automatically.

❗ Example required

Sanitize helpers

You can use these methods as sanitize_callback when describing your custom endpoints.

• sanitize_ids($ids) - the argument must be an array of ids (positive int values)
• sanitize_keys($keys) - the argument must be an array of keys
• sanitize_path($path) - argument must be path (lowercase alphanumeric characters, dot and underscores are allowed)
• sanitize_paths($paths) - the argument must be an array of paths
• floatval($value) - the argument must be float value

    'keys'		=> [
        'default'			=> [],
        'sanitize_callback' => [$this, 'sanitize_paths'],
    ],

Ajax actions

The plugin/theme can implement handling actions from the Settings Page. This is described in detail in the Sidebar actions.