云策 WordPress 开发者社区

REST API 文档

Categories

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

概述

本文档详细介绍了 WordPress REST API 中分类（Categories）的架构、字段定义及 CRUD 操作。涵盖分类记录的 JSON 模式、端点定义、查询参数和请求示例，为开发者提供完整的 API 使用指南。

关键要点

  • 分类模式包含 id、name、slug、description、parent、count、link、taxonomy、meta 等字段，每个字段有 JSON 数据类型、上下文和只读属性说明。
  • 支持通过 GET /wp/v2/categories 列出分类，可使用 context、page、per_page、search、orderby 等参数进行过滤和排序。
  • 提供创建（POST /wp/v2/categories）、检索（GET /wp/v2/categories/<id>）、更新（POST /wp/v2/categories/<id>）和删除（DELETE /wp/v2/categories/<id>）分类的端点，每个操作有对应的必需和可选参数。
  • 删除操作需设置 force=true，因为分类不支持垃圾回收机制。

代码示例

// 列出分类示例请求
$ curl https://example.com/wp-json/wp/v2/categories

// 检索特定分类示例请求
$ curl https://example.com/wp-json/wp/v2/categories/<id>

// 删除分类示例请求
$ curl -X DELETE https://example.com/wp-json/wp/v2/categories/<id>

注意事项

  • 使用 _filter 查询参数或特定上下文时，响应字段可能受限，需参考模式定义。
  • 创建分类时 name 参数为必需，其他参数如 description、slug、parent、meta 可选。
  • 更新和删除操作需指定分类的 id 参数，确保操作准确性。
📄 原文内容

Schema

The schema defines all the fields that exist within a category record. Any response from these endpoints can be expected to contain the fields below unless the `_filter` query parameter is used or the schema field only appears in a specific context.

id Unique identifier for the term.

JSON data type: integer

Read only

Context: view, embed, edit
count Number of published posts for the term.

JSON data type: integer

Read only

Context: view, edit
description HTML description of the term.

JSON data type: string

Context: view, edit
name HTML title for the term.

JSON data type: string

Context: view, embed, edit
slug An alphanumeric identifier for the term unique to its type.

JSON data type: string

Context: view, embed, edit
taxonomy Type attribution for the term.

JSON data type: string

Read only

Context: view, embed, edit

One of: category

parent The parent term ID.

JSON data type: integer

Context: view, edit
meta Meta fields.

JSON data type: object

Context: view, edit

List Categories

Query this endpoint to retrieve a collection of categories. The response you receive can be controlled and filtered using the URL query parameters below.

Definition

GET /wp/v2/categories

Example Request

$ curl https://example.com/wp-json/wp/v2/categories

Arguments

context Scope under which the request is made; determines fields present in response.

Default: view

One of: view, embed, edit

page Current page of the collection.

Default: 1

per_page Maximum number of items to be returned in result set.

Default: 10

search Limit results to those matching a string.
exclude Ensure result set excludes specific IDs.
include Limit result set to specific IDs.
order Order sort attribute ascending or descending.

Default: asc

One of: asc, desc

orderby Sort collection by term attribute.

Default: name

One of: id, include, name, slug, include_slugs, term_group, description, count

hide_empty Whether to hide terms not assigned to any posts.
parent Limit result set to terms assigned to a specific parent.
post Limit result set to terms assigned to a specific post.
slug Limit result set to terms with one or more specific slugs.

Create a Category

Arguments

<a href="#schema-description">description</a> HTML description of the term.
<a href="#schema-name">name</a> HTML title for the term.

Required: 1

<a href="#schema-slug">slug</a> An alphanumeric identifier for the term unique to its type.
<a href="#schema-parent">parent</a> The parent term ID.
<a href="#schema-meta">meta</a> Meta fields.

Definition

POST /wp/v2/categories

Retrieve a Category

Definition & Example Request

GET /wp/v2/categories/<id>

Query this endpoint to retrieve a specific category record.

$ curl https://example.com/wp-json/wp/v2/categories/<id>

Arguments

id Unique identifier for the term.
context Scope under which the request is made; determines fields present in response.

Default: view

One of: view, embed, edit

Update a Category

Arguments

<a href="#schema-id">id</a> Unique identifier for the term.
<a href="#schema-description">description</a> HTML description of the term.
<a href="#schema-name">name</a> HTML title for the term.
<a href="#schema-slug">slug</a> An alphanumeric identifier for the term unique to its type.
<a href="#schema-parent">parent</a> The parent term ID.
<a href="#schema-meta">meta</a> Meta fields.

Definition

POST /wp/v2/categories/<id>

Example Request

Delete a Category

Arguments

id Unique identifier for the term.
force Required to be true, as terms do not support trashing.

Definition

DELETE /wp/v2/categories/<id>

Example Request

$ curl -X DELETE https://example.com/wp-json/wp/v2/categories/<id>