云策 WordPress 开发者社区

REST API 文档

Glossary

查看官方原文 ↗
💡 云策文档标注

概述

本文档为WordPress REST API的术语表，面向开发者解释WP-API中的核心概念和组件，包括Controller、HTTP请求、资源、路由/端点等，帮助理解API的工作原理和交互方式。

关键要点

  • Controller：WP-API采用MVC模式，所有资源端点类继承WP_REST_Controller以确保实现通用方法。
  • HTTP请求：包括HEAD、GET、POST、PUT和DELETE等动词，对应不同操作，如GET获取数据、DELETE删除资源，类似于WordPress函数wp_remote_get()和wp_remote_post()。
  • HTTP Client：指与WP-API交互的工具，如Postman或WP_HTTP类，用于测试请求或跨站点访问。
  • Resource：WordPress中的离散实体，如Posts、Pages、Comments等，支持CRUD操作，通过API端点进行交互。
  • Routes / Endpoints：端点是API提供的函数，路由是访问端点的URL名称，一个路由可关联多个端点，取决于HTTP动词。
  • Schema：定义WP-API响应数据的格式，包括字段类型、描述和返回上下文，例如Post schema包含id、title等字段。

代码示例

GET /wp-json/wp/v2/posts  // 获取Posts集合，类似WP_Query
GET /wp-json/wp/v2/posts/123  // 获取ID为123的单个Post，类似get_post()
POST /wp-json/wp/v2/posts  // 创建新Post，类似wp_insert_post()
DELETE /wp-json/wp/v2/posts/123  // 删除ID为123的Post，类似wp_delete_post()

注意事项

  • 在没有固定链接的站点上，路由需通过rest_route参数添加到URL中，例如：http://example.com/?rest_route=wp/v2/posts/123。
📄 原文内容

New to REST APIs? Get up to speed with phrases used throughout our documentation.

Controller

Model-View-Controller is a standard pattern in software development. If you aren’t already familiar with it, you should do a bit of reading to get up to speed.

Within WP-API, we’ve adopted the controller concept to have a standard pattern for the classes representing our resource endpoints. All resource endpoints extend WP_REST_Controller to ensure they implement common methods.

HEAD, GET, POST, PUT, and DELETE Requests

These “HTTP verbs” represent the type of action a HTTP client might perform against a resource. For instance, GET requests are used to fetch a Post’s data, whereas DELETE requests are used to delete a Post. They’re collectively called “HTTP verbs” because they’re standardized across the web.

If you’re familiar with WordPress functions, a GET request is the equivalent of wp_remote_get(), and a POST request is the same as wp_remote_post().

HTTP Client

The phrase “HTTP Client” refers to the tool you use to interact with WP-API. You might use Postman (Chrome) or REST Easy (Firefox) to test requests in your browser, or httpie to test requests at the commandline.

WordPress itself provides a HTTP Client in the WP_HTTP class and related functions (e.g. wp_remote_get()). This can be used to access one WordPress site from another.

Resource

A “Resource” is a discrete entity within WordPress. You may know these resources already as Posts, Pages, Comments, Users, Terms, and so on. WP-API permits HTTP clients to perform CRUD operations against resources (CRUD stands for Create, Read, Update, and Delete).

Pragmatically, here’s how you’d typically interact with WP-API resources:

  • GET /wp-json/wp/v2/posts to get a collection of Posts. This is roughly equivalent to using WP_Query.
  • GET /wp-json/wp/v2/posts/123 to get a single Post with ID 123. This is roughly equivalent to using get_post().
  • POST /wp-json/wp/v2/posts to create a new Post. This is roughly equivalent to using wp_insert_post().
  • DELETE /wp-json/wp/v2/posts/123 to delete Post with ID 123. This is roughly equivalent to wp_delete_post().

Routes / Endpoints

Endpoints are functions available through the API. This can be things like retrieving the API index, updating a post, or deleting a comment. Endpoints perform a specific function, taking some number of parameters and return data to the client.

A route is the “name” you use to access endpoints, used in the URL. A route can have multiple endpoints associated with it, and which is used depends on the HTTP verb.

For example, with the URL `http://example.com/wp-json/wp/v2/posts/123`:

  • The “route” is wp/v2/posts/123 – The route doesn’t include wp-json because wp-json is the base path for the API itself.
  • This route has 3 endpoints:
    • GET triggers a get_item method, returning the post data to the client.
    • PUT triggers an update_item method, taking the data to update, and returning the updated post data.
    • DELETE triggers a delete_item method, returning the now-deleted post data to the client.

Note: On sites without pretty permalinks, the route is instead added to the URL as the rest_route parameter. For the above example, the full URL would then be `http://example.com/?rest_route=wp/v2/posts/123`

Schema

A “schema” is a representation of the format for WP-API’s response data. For instance, the Post schema communicates that a request to get a Post will return id, title, content, author, and other fields. Our schemas also indicate the type each field is, provide a human-readable description, and show which contexts the field will be returned in.