Custom API

Using interfaces in the API module makes it convenient to extend custom APIs.

This article uses the newapi plugin as an example to extend an API module and define an API command.

Create Plugin

Assuming the plugin ID is newapi, the content of its include.php file is as follows:

RegisterPlugin("newapi","ActivePlugin_newapi");

# The newapi_RegAPI function is hooked onto the Filter_Plugin_API_Extend_Mods interface
function ActivePlugin_newapi() {
    // ...
}

Hook Interface, Insert API Module File

Insert the myapi.php API file module into the API system. One API file module can contain multiple APIs (acts).

Newer version (1.7.3 and later) syntax:

# Operate directly when registering the plugin
function ActivePlugin_newapi() {
    // ...
    ApiAddMod('newapi', __DIR__ . '/myapi.php'); // Insert the file implementing the API into the system API with 'newapi' as the module name
}

Older version syntax:

# Implementation of the newapi_RegAPI function in include.php

function ActivePlugin_newapi() {
    Add_Filter_Plugin('Filter_Plugin_API_Extend_Mods', 'newapi_RegAPI');
}

# Insert the API implementation file myapi.php from the plugin directory into the system API with 'newapi' as the module name
function newapi_RegAPI() {
    return array('newapi' => __DIR__ . '/myapi.php');
}

Define API File Module

An API named helloworld is defined in the custom API module myapi.php.

The API function name follows a pattern: it must start with api_, followed by the registered module name with an underscore, and end with the API command name. This is how the API system routes to this function.

function api_newapi_helloworld() {
    // Perform permission validation, receive parameters, and validate parameters within the function
    $data = 'Hello world!';
    return array('data' => $data);
    // Please note: In this example, we have not validated permissions, only performed a simple data return.
}

When submitting data to the API using the POST method, you must provide the token returned after successful API login (set the Authorization request header to 'Bearer token value', or pass it in the POST request as a form input named 'token' with the token value).

If the system verifies successfully in ApiTokenVerify(), the CSRF token check will be skipped! Otherwise, the POST submission will fail!

If the above methods do not work, you can also hook the Filter_Plugin_API_VerifyCSRF_Skip interface to add the API of this mod to the array of skipped CSRF checks. The code is as follows:

// Hook the interface
Add_Filter_Plugin('Filter_Plugin_API_VerifyCSRF_Skip', 'newapi_IgnoreCSRF');

// Add helloworld of newapi to the array of skipped verification
function newapi_IgnoreCSRF(&$array) {
  $array[] = array('mod' => 'newapi', 'act' => 'helloworld');
}

API Module Whitelist and Blacklist

Use $mods_allow whitelist with caution. After enabling the whitelist, all mods not on the whitelist will be rejected.

If you only want to disable certain modules, simply add them to the $mods_disallow blacklist.

Whitelist example (new version 1.7.3 and later):

# Operate directly when registering the plugin
function ActivePlugin_newapi() {
    // ...
    ApiAddAllowMod('newapi'); // Allow all APIs under the newapi module
    ApiAddAllowMod('member', 'login'); // Allow login under the member module
    // After enabling the whitelist, only APIs under the newapi module and the login API under the member module can be accessed!

    ApiAddAllowMod('member', 'login'); // Cancel permission for login under the member module
}

Whitelist example (older version):

Add_Filter_Plugin('Filter_Plugin_API_CheckMods', 'newapi_CheckMods');

function newapi_CheckMods(&$mods_allow, &$mods_disallow) {
    $mods_allow[] = array('newapi' => ''); // Allow all APIs under the newapi module
    $mods_allow[] = array('member' => 'login'); // Allow login under the member module
    // After enabling the whitelist, only APIs under the newapi module and the login API under the member module can be accessed!
}

Blacklist example (new version 1.7.3 and later):

# Operate directly when registering the plugin
function ActivePlugin_newapi() {
    // ...
    ApiAddDisallowMod('newapi', 'postdata'); // Disable postdata under the newapi module
    ApiAddDisallowMod('system'); // Disable all APIs under the system module
    // After enabling the blacklist, all APIs not within the disabled range can be accessed!

    ApiRemoveDisallowMod('newapi', 'postdata'); // Cancel disabling postdata under the newapi module
}

Blacklist example (older version):

Add_Filter_Plugin('Filter_Plugin_API_CheckMods', 'newapi_CheckMods');

function newapi_CheckMods(&$mods_allow, &$mods_disallow) {
    $mods_disallow[] = array('newapi' => 'postdata'); // Disable postdata under the newapi module
    $mods_disallow[] = array('system' => ''); // Disable all APIs under the system module
    // After enabling the blacklist, all APIs not within the disabled range can be accessed!
}

Access API

API Access URL:

https://testsite/zb_system/api.php?mod=newapi&act=helloworld

Here, the mod parameter is the module name, and the act parameter is the API command name.

The returned data content is as follows:

{
    "code":200,
    "message":"OK",
    "data":"Hello world!",
    "error":null,
    "runtime":{"time":"31.89","query":4,"memory":-1100}
}

The code used in this article requires Z-BlogPHP version 1.7.1.2990 or higher.