REST API 不仅仅是一组默认路由。它也是创建自定义路由和端点的工具。前端提供了一组默认的 URL 映射，但用于创建它们的工具（如 API 和查询类：等）也可用于创建自己的 URL 映射，或自定义查询。

本文档详细介绍了如何使用您自己的端点创建完全自定义的路由。我们将首先通过一个简短的示例，然后将其扩展到内部使用的完整控制器模式。

良好的基础

所以您想向 API 添加自定义端点？惊人的！让我们从一个简单的例子开始。

我们从一个如下所示的简单函数开始：

<?php
/**
 * Grab latest post title by an author!
 *
 * @param array $data Options for the function.
 * @return string|null Post title for the latest,
 * or null if none.
 */
function my_awesome_func( $data ) {
  $posts = get_posts( array(
    'author' => $data['id'],
  ) );
 
  if ( empty( $posts ) ) {
    return null;
  }

 
  return $posts[0]->post_title;
}

要通过 API 提供此功能，我们需要注册一个路由。这告诉 API 使用我们的函数来响应给定的请求。我们通过一个名为 的函数来做到这一点，该函数应该在 的回调中调用。

我们需要向它传递三件事：命名空间、我们想要的路由和选项。我们稍后会回到命名空间wordpress调用参数，但现在让我们选择 /v1。我们用 //{id} 匹配路由，其中​​ {id} 是一个整数。

<?php
add_action( 'rest_api_init', function () {
  register_rest_route( 'myplugin/v1', '/author/(?P\d+)', array(
    'methods' => 'GET',
    'callback' => 'my_awesome_func',
  ) );
} );

目前，我们只注册路由的一个端点。 （"Route" 是 URL，"" 是对应的方法和 URL），如果您的站点域是 wp-json 并且您保留 API 路径的 wp-jsonwordpress调用参数，那么完整的 URL 将是 (?P\d+ )。每个路由可以有任意数量的端点，对于每个端点，您可以定义允许的 HTTP 方法、用于响应该请求的回调函数以及用于创建自定义权限的权限回调。此外，您可以在请求中定义允许的字段，每个字段指定一个默认值、一个清理回调、一个验证回调以及是否需要该字段。

命名空间

命名空间是端点 URL 的第一部分。它们应该用作供应商/包前缀，以防止自定义路由之间发生冲突。命名空间允许两个插件添加具有不同功能的同名路由。

命名空间通常应遵循 /v1 模式，其中供应商通常是您的插件或主题，v1 代表 API 的第一个版本。如果您需要破坏与新端点的兼容性，则可以将其限制为 v2。

上述情况，来自两个不同插件的两个同名路由，要求所有提供者使用唯一的命名空间。供应商功能前缀、类前缀和/或类名称空间不会在主题或插件中使用，否则将不会这样做，这是非常重要的。

使用命名空间的另一个好处是客户端可以检测到对您的自定义 API 的支持。 API 索引列出了站点上可用的命名空间：

{

  "name": "WordPress Site",
  "description": "Just another WordPress site",
  "url": "http://example.com/",
  "namespaces": [
    "wp/v2",
    "vendor/v1",
    "myplugin/v1",
    "myplugin/v2",
  ]
}

如果客户想要检查您的 API 是否存在于网站上，他们可以查看此列表。 （有关更多信息，请参阅探索指南。）

参数

默认情况下，路由接受请求中传入的所有参数。这些组合成一组参数，然后添加到对象中，作为第一个参数传递给您的端点：

<?php
function my_awesome_func( WP_REST_Request $request ) {
  // You can access parameters via direct array access on the object:
 $param = $request['some_param'];
 
  // Or via the helper method:
 $param = $request->get_param( 'some_param' );

 
  // You can get the combined, merged set of parameters:
 $parameters = $request->get_params();
 
  // The individual sets of parameters are also available, if needed:
 $parameters = $request->get_url_params();
  $parameters = $request->get_query_params();
  $parameters = $request->get_body_params();
  $parameters = $request->get_json_params();
  $parameters = $request->get_default_params();
 
  // Uploads aren't merged in, but can be accessed separately:
 $parameters = $request->get_file_params();
}

（要确切了解参数是如何组合的，请查看 ::() 的源代码；基本顺序是正文、查询、URL，然后是默认值）。

一般情况下，您将获得所有参数不变。但是，您可以在注册路由时注册自己的参数，以便对其进行清理和验证。

如果请求有 -type:/json 标头集合和正文中的有效 JSON，则 then() 会将解析后的 JSON 正文作为关联数组返回。

参数被定义为每个端点的关键参数中的映射（在回调选项旁边）。此映射使用该键的参数名称，其值是该参数的选项映射。该数组可以包含默认键、必需键和 .

使用并允许主回调仅处理请求并使用类来准备要返回的数据。通过使用这两个回调，您将能够安全地假设您的输入在处理时是有效且安全的。

通过我们前面的例子，我们可以确保传入的参数总是一个数字：

<?php
add_action( 'rest_api_init', function () {
  register_rest_route( 'myplugin/v1', '/author/(?P\d+)', array(
    'methods' => 'GET',
    'callback' => 'my_awesome_func',
    'args' => array(
      'id' => array(
        'validate_callback' => function($param, $request, $key) {
          return is_numeric( $param );
        }
      ),
    ),
  ) );
} );

你也可以传递一个函数名给wordpress做网站，但是直接传递一些函数，比如 .我们希望最终从根本上解决这个问题。

我们也可以使用类似 ''=>'' 的东西，但是验证会抛出一个错误，让客户知道他们做错了什么。当您宁愿更改正在输入的数据而不是抛出错误（例如无效的 HTML）时，清理很有用。

返回值

调用回调后，返回值会转换成JSON返回给客户端。这允许您返回基本上任何形式的数据。在上面的示例中，我们返回一个字符串或 null，这些字符串由 API 自动处理并转换为 JSON。

与任何其他函数一样，您也可以返回一个实例。此错误消息将与 500 内部服务错误状态代码一起传递给客户端。您可以通过将实例数据中的状态选项设置为代码来进一步自定义错误，例如400 错误的输入数据。

前面的例子，我们现在可以返回一个错误实例：

<?php
/**
 * Grab latest post title by an author!
 *
 * @param array $data Options for the function.
 * @return string|null Post title for the latest,
 * or null if none.
 */
function my_awesome_func( $data ) {
  $posts = get_posts( array(
    'author' => $data['id'],
  ) );
 
  if ( empty( $posts ) ) {
    return new WP_Error( 'awesome_no_author', 'Invalid author', array( 'status' => 404 ) );
  }
 
  return $posts[0]->post_title;
}

当作者没有属于他们的任何帖子时wordpress网站建设，这将向客户端返回 404 Not Found 错误：

文章来自互联网，侵权请联系删除，文章阐述观点来自文章出处，并不代表本站观点。 www.8001717.cn

返回