WP rest api 文字教程

wptutor 2023-12-18 WordPress教程 Leave a comment 83 Views

概述

REST API 为我们提供了一种将 URI 与 WordPress 安装中的各种资源相匹配的方法。默认情况下，如果您启用了漂亮的永久链接，则 WordPress REST API “存在”于 /wp-json/。在我们的 WordPress 网站https://ourawesomesite.com`, we can access the REST API's index by making aGETrequest tohttps://ourawesomesite.com/wp-json/`。该索引提供了有关特定 WordPress 安装可用的路由、支持哪些 HTTP 方法以及注册了哪些端点的信息。

路由和断点

端点是通过 API 可用的功能。这可以是检索 API 索引、更新帖子或删除评论等。端点执行特定功能，获取一定数量的参数并将数据返回给客户端。

路由是您用于访问端点的“名称”，在 URL 中使用。一个路由可以有多个与其关联的端点，使用哪个端点取决于 HTTP 动词。

例如，使用 URL“http://example.com/wp-json/wp/v2/posts/123”：

“路线”为 wp/v2/posts/123 – 该路线不包含 wp-json，因为 wp-json 是基本路径API 本身。
该路线有 3 个端点：
- GET 触发 get_item 方法，将发布数据返回给客户端。
- PUT 触发 update_item 方法，获取要更新的数据，并返回更新后的发布数据。
- DELETE 触发 delete_item 方法，将现已删除的帖子数据返回给客户端。

rest_route 参数添加到 URL 中。对于上面的示例，完整的 URL 将是 http://example.com/?rest_route=/wp/v2/posts/123

创建断点

如果我们想要创建一个端点，在收到 GET 请求时返回短语“Hello World，这是 WordPress REST API”，我们首先需要注册该端点的路由。要注册路由，您应该使用 register_rest_route() 函数。需要在 rest_api_init 操作挂钩上调用它。 register_rest_route() 处理到端点的路由的所有映射。让我们尝试创建一个“Hello World，这是 WordPress REST API”路线。

/**
 * This is our callback function that embeds our phrase in a WP_REST_Response
 */
function prefix_get_endpoint_phrase() {
    // rest_ensure_response() wraps the data we want to return into a WP_REST_Response, and ensures it will be properly returned.
    return rest_ensure_response( 'Hello World, this is the WordPress REST API' );
}

/**
 * This function is where we register our routes for our example endpoint.
 */
function prefix_register_example_routes() {
    // register_rest_route() handles more arguments but we are going to stick to the basics for now.
    register_rest_route( 'hello-world/v1', '/phrase', array(
        // By using this constant we ensure that when the WP_REST_Server changes our readable endpoints will work as intended.
        'methods'  => WP_REST_Server::READABLE,
        // Here we register our callback. The callback is fired when this endpoint is matched by the WP_REST_Server class.
        'callback' => 'prefix_get_endpoint_phrase',
    ) );
}

add_action( 'rest_api_init', 'prefix_register_example_routes' );

传递给 register_rest_route() 的第一个参数是命名空间，它为我们提供了一种对路由进行分组的方法。传入的第二个参数是资源路径或资源库。对于我们的示例，我们检索的资源是“Hello World，这是 WordPress REST API”短语。第三个参数是选项数组。我们指定端点可以使用哪些方法以及端点匹配时应该发生什么回调（可以做更多事情，但这些是基础）。

第三个参数还允许我们提供权限回调，它可以将端点的访问限制为仅某些用户。第三个参数还提供了一种为端点注册参数的方法，以便请求可以修改端点的响应。我们将在本指南的端点部分介绍这些概念。

当我们访问 https://ourawesomesite.com/wp-json/hello-world/v1/phrase 时，我们现在可以看到我们的 REST API 友好地向我们打招呼。让我们更深入地了解一下路线。

路由

REST API 中的路由由 URI 表示。路线本身是添加到 https://ourawesomesite.com/wp-json`. The index route for the API is/which is whyhttps://ourawesomesite.com/wp-json/` 末尾的内容，返回所有可用信息API。所有路由都应该构建在该路由上，wp-json部分可以更改，但一般情况下建议保持不变。

我们希望确保我们的路线是唯一的。例如，我们可以有这样的书籍路径：/books。我们的图书路线现在位于 https://ourawesomesite.com/wp-json/books`. However, this is not a good practice as we would end up polluting potential routes for the API. What if another plugin we wanted to register a books route as well? We would be in big trouble in that case, as the two routes would conflict with each other and only one could be used. The fourth parameter toregister_rest_route() ` 是一个布尔值，表示该路线是否应覆盖现有路线。

override 参数也没有真正解决我们的问题，因为两个路由都可以覆盖，或者我们希望将两个路由用于不同的事情。这就是为我们的路由使用命名空间的用武之地。

命名空间

向路由添加命名空间非常重要。 “核心”端点使用 wp/v2 命名空间。

请勿将任何内容放入 wp命名空间中，除非您创建端点的目的是将它们合并到核心中。

核心端点命名空间中有一些需要注意的关键事项。命名空间的第一部分是wp，代表供应商名称； WordPress。对于我们的插件，我们希望为命名空间的供应商部分提供唯一的名称。在上面的示例中，我们使用了hello-world。

供应商部分之后是命名空间的版本部分。 “核心”端点利用 v2 代表 WordPress REST API 的版本 2。如果您正在编写插件，则只需创建新端点并提高您提供的版本号即可保持 REST API 端点的向后兼容性。这样原始的 v1 和 v2 端点都可以访问。

命名空间后面的路由部分是资源路径。

资源路径

资源路径应表示端点与什么资源关联。在上面使用的示例中，我们使用单词 phrase 来表示我们正在交互的资源是一个短语。为了避免任何冲突，我们注册的每个资源路径在命名空间中也应该是唯一的。资源路径应用于定义给定命名空间内的不同资源路由。

假设我们有一个处理一些基本电子商务功能的插件。我们将有两种主要资源类型：订单和产品。订单是对产品的请求，但不是产品本身。同样的概念也适用于产品。尽管这些资源是相关的，但它们不是同一件事，每个资源都应该位于单独的资源路径中。我们的电子商务插件的路线最终将如下所示：/my-shop/v1/orders 和 /my-shop/v1/products。

使用这样的路由，我们希望每个路由返回订单或产品的集合。如果我们想通过 ID 获取特定产品，我们需要在路由中使用路径变量。

路径变量

路径变量使我们能够添加动态路由。为了扩展我们的电子商务路线，我们可以注册一条获取单个产品的路线。

/**
 * This is our callback function to return our products.
 *
 * @param WP_REST_Request $request This function accepts a rest request to process data.
 */
function prefix_get_products( $request ) {
    // In practice this function would fetch the desired data. Here we are just making stuff up.
    $products = array(
        '1' => 'I am product 1',
        '2' => 'I am product 2',
        '3' => 'I am product 3',
    );

    return rest_ensure_response( $products );
}

/**
 * This is our callback function to return a single product.
 *
 * @param WP_REST_Request $request This function accepts a rest request to process data.
 */
function prefix_get_product( $request ) {
    // In practice this function would fetch the desired data. Here we are just making stuff up.
    $products = array(
        '1' => 'I am product 1',
        '2' => 'I am product 2',
        '3' => 'I am product 3',
    );

    // Here we are grabbing the 'id' path variable from the $request object. WP_REST_Request implements ArrayAccess, which allows us to grab properties as though it is an array.
    $id = (string) $request['id'];

    if ( isset( $products[ $id ] ) ) {
        // Grab the product.
        $product = $products[ $id ];

        // Return the product as a response.
        return rest_ensure_response( $product );
    } else {
        // Return a WP_Error because the request product was not found. In this case we return a 404 because the main resource was not found.
        return new WP_Error( 'rest_product_invalid', esc_html__( 'The product does not exist.', 'my-text-domain' ), array( 'status' => 404 ) );
    }

    // If the code somehow executes to here something bad happened return a 500.
    return new WP_Error( 'rest_api_sad', esc_html__( 'Something went horribly wrong.', 'my-text-domain' ), array( 'status' => 500 ) );
}

/**
 * This function is where we register our routes for our example endpoint.
 */
function prefix_register_product_routes() {
    // Here we are registering our route for a collection of products.
    register_rest_route( 'my-shop/v1', '/products', array(
        // By using this constant we ensure that when the WP_REST_Server changes our readable endpoints will work as intended.
        'methods'  => WP_REST_Server::READABLE,
        // Here we register our callback. The callback is fired when this endpoint is matched by the WP_REST_Server class.
        'callback' => 'prefix_get_products',
    ) );
    // Here we are registering our route for single products. The (?P<id>[\d]+) is our path variable for the ID, which, in this example, can only be some form of positive number.
    register_rest_route( 'my-shop/v1', '/products/(?P<id>[\d]+)', array(
        // By using this constant we ensure that when the WP_REST_Server changes our readable endpoints will work as intended.
        'methods'  => WP_REST_Server::READABLE,
        // Here we register our callback. The callback is fired when this endpoint is matched by the WP_REST_Server class.
        'callback' => 'prefix_get_product',
    ) );
}

add_action( 'rest_api_init', 'prefix_register_product_routes' );

上面的例子涵盖了很多内容。需要注意的重要部分是，在我们注册的第二个路由中，我们将路径变量 /(?P<id>[\d]+) 添加到我们的资源路径 /products 中。路径变量是一个正则表达式。在这种情况下，它使用 [\d]+ 来表示应该是至少一次的任何数字字符。如果您对资源使用数字 ID，那么这是如何使用路径变量的一个很好的示例。当使用路径变量时，我们现在必须小心可以匹配的内容，因为它是用户输入。

幸运的是，正则表达式会过滤掉任何非数字的内容。但是，如果所请求 ID 的产品不存在怎么办？我们需要进行错误处理。您可以在上面的代码示例中看到我们处理错误的基本方式。当您在端点回调中返回 WP_Error 时，API 服务器将自动处理向客户端提供错误的情况。

虽然本节是关于路由的，但我们已经介绍了很多关于端点的内容。端点和路由是相互关联的，但它们肯定也有区别。

断点

端点是路由需要映射到的目的地。对于任何给定的路由，您可以向其注册多个不同的端点。我们将扩展我们虚构的电子商务插件，以更好地显示路由和端点之间的区别。我们将创建存在于 /wp-json/my-shop/v1/products/ 路由上的两个端点。一个端点使用 HTTP 动词 GET 获取产品，另一个端点使用 HTTP 动词 POST 创建新产品。

/**
 * This is our callback function to return our products.
 *
 * @param WP_REST_Request $request This function accepts a rest request to process data.
 */
function prefix_get_products( $request ) {
    // In practice this function would fetch the desired data. Here we are just making stuff up.
    $products = array(
        '1' => 'I am product 1',
        '2' => 'I am product 2',
        '3' => 'I am product 3',
    );

    return rest_ensure_response( $products );
}

/**
 * This is our callback function to return a single product.
 *
 * @param WP_REST_Request $request This function accepts a rest request to process data.
 */
function prefix_create_product( $request ) {
    // In practice this function would create a product. Here we are just making stuff up.
   return rest_ensure_response( 'Product has been created' );
}

/**
 * This function is where we register our routes for our example endpoint.
 */
function prefix_register_product_routes() {
    // Here we are registering our route for a collection of products and creation of products.
    register_rest_route( 'my-shop/v1', '/products', array(
        array(
            // By using this constant we ensure that when the WP_REST_Server changes, our readable endpoints will work as intended.
            'methods'  => WP_REST_Server::READABLE,
            // Here we register our callback. The callback is fired when this endpoint is matched by the WP_REST_Server class.
            'callback' => 'prefix_get_products',
        ),
        array(
            // By using this constant we ensure that when the WP_REST_Server changes, our create endpoints will work as intended.
            'methods'  => WP_REST_Server::CREATABLE,
            // Here we register our callback. The callback is fired when this endpoint is matched by the WP_REST_Server class.
            'callback' => 'prefix_create_product',
        ),
    ) );
}

add_action( 'rest_api_init', 'prefix_register_product_routes' );

根据我们用于路由的 HTTP 方法/wp-json/my-shop/v1/products，我们会匹配到不同的端点并触发不同的回调。当我们使用 POST 时，我们会触发 prefix_create_product() 回调，当我们使用 GET 时，我们会触发 prefix_get_products() 回调。

有多种不同的 HTTP 方法，REST API 可以使用其中任何一种方法。

HTTP方法

HTTP 方法有时称为 HTTP 动词。它们只是通过 HTTP 进行通信的不同方式。 WordPress REST API 使用的主要有：

GET应该用于从 API 检索数据。
POST应用于创建新资源（即用户、帖子、分类法）。
PUT应该用于更新资源。
DELETE应该用于删除资源。
OPTIONS应该用来提供有关我们资源的背景信息。

需要注意的是，并非所有客户端都支持这些方法，因为它们是在 HTTP 1.1 中引入的。幸运的是，API 为这些不幸的情况提供了解决方法。如果您想删除资源但无法发送 DELETE 请求，则可以使用 _method 参数或 X-HTTP-Method-Override您的请求中的标头。其工作原理是，您将向“https://ourawesomesite.com/wp-json/my-shop/v1/products/1?_method=DELETE”发送 POST 请求。现在，您将删除产品编号 1，即使您的客户端无法在请求中发送正确的 HTTP 方法，或者可能存在防火墙阻止 DELETE 请求。

HTTP 方法与路由和回调相结合，构成了端点的核心。

回调

REST API 目前仅支持两种类型的端点回调： callback 和 permission_callback。主回调应该处理与资源的交互。权限回调应该处理用户有权访问端点的内容。您可以通过在注册端点时添加附加信息来添加附加回调。然后，您可以挂钩 rest_pre_dispatch、rest_dispatch_request 或 rest_post_dispatch 挂钩来触发新的自定义回调。

端点回调

删除端点的主回调应该只删除资源并在响应中返回它的副本。创建端点的主回调应该只创建资源并返回与新创建的数据匹配的响应。更新回调应该只修改实际存在的资源。读取回调应该只检索已经存在的数据。考虑幂等性的概念很重要。

在 REST API 上下文中，幂等性意味着如果您向端点发出相同的请求，服务器将以相同的方式处理该请求。想象一下，如果我们的读取端点不是幂等的。每当我们向它发出请求时，即使我们只是试图获取数据，我们的服务器的状态也会被该请求修改。这可能是灾难性的。每当有人从您的服务器获取数据时，内部都会发生变化。重要的是要确保读取、更新和删除端点不会产生令人讨厌的副作用，并且只坚持它们的预期用途。

在 REST API 中，幂等性的概念与 HTTP 方法而不是端点回调相关。使用 GET、HEAD、TRACE、OPTIONS、不应产生任何副作用。请求不是幂等的，通常用于创建资源。如果您创建了一种幂等创建方法，那么您将只创建一个资源，因为当您发出相同的请求时，不会对服务器产生更多副作用。对于创建来说，如果您一遍又一遍地发出相同的请求，服务器每次都会生成新的资源。PUTDELETEPOST

为了限制端点的使用，我们需要注册一个权限回调。

权限回调

权限回调对于 WordPress REST API 的安全性极其重要。如果您有任何不应公开显示的私有数据，则需要为端点注册权限回调。下面是如何注册权限回调的示例。

/**
 * This is our callback function that embeds our resource in a WP_REST_Response
 */
function prefix_get_private_data() {
    // rest_ensure_response() wraps the data we want to return into a WP_REST_Response, and ensures it will be properly returned.
    return rest_ensure_response( 'This is private data.' );
}

/**
 * This is our callback function that embeds our resource in a WP_REST_Response
 */
function prefix_get_private_data_permissions_check() {
    // Restrict endpoint to only users who have the edit_posts capability.
    if ( ! current_user_can( 'edit_posts' ) ) {
        return new WP_Error( 'rest_forbidden', esc_html__( 'OMG you can not view private data.', 'my-text-domain' ), array( 'status' => 401 ) );
    }

    // This is a black-listing approach. You could alternatively do this via white-listing, by returning false here and changing the permissions check.
    return true;
}

/**
 * This function is where we register our routes for our example endpoint.
 */
function prefix_register_example_routes() {
    // register_rest_route() handles more arguments but we are going to stick to the basics for now.
    register_rest_route( 'my-plugin/v1', '/private-data', array(
        // By using this constant we ensure that when the WP_REST_Server changes our readable endpoints will work as intended.
        'methods'  => WP_REST_Server::READABLE,
        // Here we register our callback. The callback is fired when this endpoint is matched by the WP_REST_Server class.
        'callback' => 'prefix_get_private_data',
        // Here we register our permissions callback. The callback is fired before the main callback to check if the current user can access the endpoint.
        'permission_callback' => 'prefix_get_private_data_permissions_check',
    ) );
}

add_action( 'rest_api_init', 'prefix_register_example_routes' );

如果您在未启用任何身份验证的情况下尝试此端点，那么您还将收到错误响应，从而阻止您查看数据。身份验证是一个很大的主题，最终将创建本章的一部分来向您展示如何创建自己的身份验证过程。

论点

向端点发出请求时，您可能需要指定额外的参数来更改响应。可以在注册端点时添加这些额外参数。让我们看一个如何将参数与端点一起使用的示例。

/**
 * This is our callback function that embeds our resource in a WP_REST_Response
 */
function prefix_get_colors( $request ) {
    // In practice this function would fetch the desired data. Here we are just making stuff up.
    $colors = array(
        'blue',
        'blue',
        'red',
        'red',
        'green',
        'green',
    );

    if ( isset( $request['filter'] ) ) {
       $filtered_colors = array();
       foreach ( $colors as $color ) {
           if ( $request['filter'] === $color ) {
               $filtered_colors[] = $color;
           }
       }
       return rest_ensure_response( $filtered_colors );
    }
    return rest_ensure_response( $colors );
}

/**
 * We can use this function to contain our arguments for the example product endpoint.
 */
function prefix_get_color_arguments() {
    $args = array();
    // Here we are registering the schema for the filter argument.
    $args['filter'] = array(
        // description should be a human readable description of the argument.
        'description' => esc_html__( 'The filter parameter is used to filter the collection of colors', 'my-text-domain' ),
        // type specifies the type of data that the argument should be.
        'type'        => 'string',
        // enum specified what values filter can take on.
        'enum'        => array( 'red', 'green', 'blue' ),
    );
    return $args;
}

/**
 * This function is where we register our routes for our example endpoint.
 */
function prefix_register_example_routes() {
    // register_rest_route() handles more arguments but we are going to stick to the basics for now.
    register_rest_route( 'my-colors/v1', '/colors', array(
        // By using this constant we ensure that when the WP_REST_Server changes our readable endpoints will work as intended.
        'methods'  => WP_REST_Server::READABLE,
        // Here we register our callback. The callback is fired when this endpoint is matched by the WP_REST_Server class.
        'callback' => 'prefix_get_colors',
        // Here we register our permissions callback. The callback is fired before the main callback to check if the current user can access the endpoint.
        'args' => prefix_get_color_arguments(),
    ) );
}

add_action( 'rest_api_init', 'prefix_register_example_routes' );

我们现在已为此示例指定了filter 参数。当我们请求端点时，我们可以将参数指定为查询参数。如果我们向“https://ourawesomesitem.com/my-colors/v1/colors?filter=blue”发出 GET 请求，我们将仅返回集合中的蓝色。您还可以将它们作为请求正文中的正文参数传递，而不是在查询字符串中传递。要了解查询参数和主体参数之间的区别，您应该阅读 HTTP 规范。查询参数存在于附加到 URL 上的查询字符串中，而正文参数则直接嵌入到 HTTP 请求的正文中。

我们已经为端点创建了一个参数，但是我们如何验证该参数是一个字符串，并判断它是否与值红色、绿色或蓝色匹配。为此，我们需要为我们的参数指定一个验证回调。

验证

验证和清理对于 API 的安全性极其重要。验证回调（在 WP 4.6+ 中）在清理回调之前触发。您应该使用 validate_callback 作为参数来验证您收到的输入是否有效。在主回调处理参数之前，应使用 sanitize_callback 转换参数输入或清除参数中不需要的部分。

在上面的示例中，我们需要验证filter 参数是否是一个字符串，并且它与值 red、green 或 blue 匹配。我们来看看添加 validate_callback 后的代码是什么样的。

/**
 * This is our callback function that embeds our resource in a WP_REST_Response
 */
function prefix_get_colors( $request ) {
    // In practice this function would fetch more practical data. Here we are just making stuff up.
    $colors = array(
        'blue',
        'blue',
        'red',
        'red',
        'green',
        'green',
    );

    if ( isset( $request['filter'] ) ) {
       $filtered_colors = array();
       foreach ( $colors as $color ) {
           if ( $request['filter'] === $color ) {
               $filtered_colors[] = $color;
           }
       }
       return rest_ensure_response( $filtered_colors );
    }
    return rest_ensure_response( $colors );
}
/**
 * Validate a request argument based on details registered to the route.
 *
 * @param  mixed            $value   Value of the 'filter' argument.
 * @param  WP_REST_Request  $request The current request object.
 * @param  string           $param   Key of the parameter. In this case it is 'filter'.
 * @return WP_Error|boolean
 */
function prefix_filter_arg_validate_callback( $value, $request, $param ) {
    // If the 'filter' argument is not a string return an error.
    if ( ! is_string( $value ) ) {
        return new WP_Error( 'rest_invalid_param', esc_html__( 'The filter argument must be a string.', 'my-text-domain' ), array( 'status' => 400 ) );
    }

    // Get the registered attributes for this endpoint request.
    $attributes = $request->get_attributes();

    // Grab the filter param schema.
    $args = $attributes['args'][ $param ];

    // If the filter param is not a value in our enum then we should return an error as well.
    if ( ! in_array( $value, $args['enum'], true ) ) {
        return new WP_Error( 'rest_invalid_param', sprintf( __( '%s is not one of %s' ), $param, implode( ', ', $args['enum'] ) ), array( 'status' => 400 ) );
    }
}

/**
 * We can use this function to contain our arguments for the example product endpoint.
 */
function prefix_get_color_arguments() {
    $args = array();
    // Here we are registering the schema for the filter argument.
    $args['filter'] = array(
        // description should be a human readable description of the argument.
        'description' => esc_html__( 'The filter parameter is used to filter the collection of colors', 'my-text-domain' ),
        // type specifies the type of data that the argument should be.
        'type'        => 'string',
        // enum specified what values filter can take on.
        'enum'        => array( 'red', 'green', 'blue' ),
        // Here we register the validation callback for the filter argument.
        'validate_callback' => 'prefix_filter_arg_validate_callback',
    );
    return $args;
}

/**
 * This function is where we register our routes for our example endpoint.
 */
function prefix_register_example_routes() {
    // register_rest_route() handles more arguments but we are going to stick to the basics for now.
    register_rest_route( 'my-colors/v1', '/colors', array(
        // By using this constant we ensure that when the WP_REST_Server changes our readable endpoints will work as intended.
        'methods'  => WP_REST_Server::READABLE,
        // Here we register our callback. The callback is fired when this endpoint is matched by the WP_REST_Server class.
        'callback' => 'prefix_get_colors',
        // Here we register our permissions callback. The callback is fired before the main callback to check if the current user can access the endpoint.
        'args' => prefix_get_color_arguments(),
    ) );
}

add_action( 'rest_api_init', 'prefix_register_example_routes' );

消毒

在上面的示例中，我们不需要使用 sanitize_callback，因为我们将输入限制为仅包含枚举中的值。如果我们没有严格的验证并接受任何字符串作为参数，我们肯定需要注册一个sanitize_callback。如果我们想要更新内容字段并且用户输入了类似 alert('ZOMG Hacking you'); 的内容，该怎么办？该字段值可能是可执行脚本。为了去除不需要的数据或将数据转换为所需的格式，我们需要为我们的参数注册 sanitize_callback 。以下是如何使用 WordPress 的 sanitize_text_field() 进行清理回调的示例：

/**
 * This is our callback function that embeds our resource in a WP_REST_Response.
 *
 * The parameter is already sanitized by this point so we can use it without any worries.
 */
function prefix_get_item( $request ) {
    if ( isset( $request['data'] ) ) {
        return rest_ensure_response( $request['data'] );
    }

    return new WP_Error( 'rest_invalid', esc_html__( 'The data parameter is required.', 'my-text-domain' ), array( 'status' => 400 ) );
}

/**
 * Validate a request argument based on details registered to the route.
 *
 * @param  mixed            $value   Value of the 'filter' argument.
 * @param  WP_REST_Request  $request The current request object.
 * @param  string           $param   Key of the parameter. In this case it is 'filter'.
 * @return WP_Error|boolean
 */
function prefix_data_arg_validate_callback( $value, $request, $param ) {
    // If the 'data' argument is not a string return an error.
    if ( ! is_string( $value ) ) {
        return new WP_Error( 'rest_invalid_param', esc_html__( 'The filter argument must be a string.', 'my-text-domain' ), array( 'status' => 400 ) );
    }
}

/**
 * Sanitize a request argument based on details registered to the route.
 *
 * @param  mixed            $value   Value of the 'filter' argument.
 * @param  WP_REST_Request  $request The current request object.
 * @param  string           $param   Key of the parameter. In this case it is 'filter'.
 * @return WP_Error|boolean
 */
function prefix_data_arg_sanitize_callback( $value, $request, $param ) {
    // It is as simple as returning the sanitized value.
    return sanitize_text_field( $value );
}

/**
 * We can use this function to contain our arguments for the example product endpoint.
 */
function prefix_get_data_arguments() {
    $args = array();
    // Here we are registering the schema for the filter argument.
    $args['data'] = array(
        // description should be a human readable description of the argument.
        'description' => esc_html__( 'The data parameter is used to be sanitized and returned in the response.', 'my-text-domain' ),
        // type specifies the type of data that the argument should be.
        'type'        => 'string',
        // Set the argument to be required for the endpoint.
        'required'    => true,
        // We are registering a basic validation callback for the data argument.
        'validate_callback' => 'prefix_data_arg_validate_callback',
        // Here we register the validation callback for the filter argument.
        'sanitize_callback' => 'prefix_data_arg_sanitize_callback',
    );
    return $args;
}

/**
 * This function is where we register our routes for our example endpoint.
 */
function prefix_register_example_routes() {
    // register_rest_route() handles more arguments but we are going to stick to the basics for now.
    register_rest_route( 'my-plugin/v1', '/sanitized-data', array(
        // By using this constant we ensure that when the WP_REST_Server changes our readable endpoints will work as intended.
        'methods'  => WP_REST_Server::READABLE,
        // Here we register our callback. The callback is fired when this endpoint is matched by the WP_REST_Server class.
        'callback' => 'prefix_get_item',
        // Here we register our permissions callback. The callback is fired before the main callback to check if the current user can access the endpoint.
        'args' => prefix_get_data_arguments(),
    ) );
}

add_action( 'rest_api_init', 'prefix_register_example_routes' );

概括

我们已经介绍了注册 WordPress REST API 端点的基础知识。路由是我们的端点所在的 URI。端点是回调、方法、参数和其他选项的集合。使用 register_rest_route() 时，每个端点都会映射到一条路由。默认情况下，端点可以支持各种 HTTP 方法、主回调、权限回调和注册参数。我们可以注册端点来涵盖与 WordPress 交互的任何用例。端点作为与 REST API 的核心交互点，但还有许多其他主题需要探索和理解，以充分利用这个强大的 API。