Категории (categories)

Эти маршруты позволяют получить/создать/обновить/удалить рубрики (категории).

Возможные маршруты (конечные точки маршрутов описаны ниже):

/wp/v2/categories       // работает со всеми рубриками
/wp/v2/categories/{ID}  // работает с указанной вместо {ID} рубрикой

Класс контроллера: WP_REST_Terms_Controller{}

Схема ресурса

Схема показывает все поля, которые существуют для объекта: поля объекта которые вернет запрос.

Параметр Контекст Описание
id
число
view, edit, embed ID термина (рубрики).
Только для чтения.
count
число
view, edit Количество записей находящихся в термине (рубрике).
Только для чтения.
description
строка
view, edit Описание термина (рубрики).
link
строка, uri
view, edit, embed URL термина (рубрики).
Только для чтения.
name
строка
view, edit, embed Название термина (рубрики).
slug
строка
view, edit, embed Слаг (ярлык) термина (рубрики), обычно создается из названия.
taxonomy
строка
view, edit, embed Название таксономии.
Только для чтения.
Может быть: category, post_tag, nav_menu, link_category, post_format
parent
число
view, edit ID родительского термина.
meta
объект
view, edit Мета поля.

Контекст — показывает какие поля объекта вернуться в ответе при создании запроса в указанном контексте. Например, при обновлении или создании рубрики вернуться поля соответствующие контексту edit.

wp/v2/categories

Запрос OPTIONS к маршруту вернет полное описание этого маршрута: эндпоинты их параметры, схему.

$ curl -X OPTIONS -i http://demo.wp-api.org/wp-json/wp/v2/categories
GitHub
{
    "namespace": "wp/v2",
    "methods": [
        "GET",
        "POST"
    ],
    "endpoints": [
        {
            "methods": [
                "GET"
            ],
            "args": {
                "context": {
                    "required": false,
                    "default": "view",
                    "enum": [
                        "view",
                        "embed",
                        "edit"
                    ],
                    "description": "Рамки в которых сделан запрос, определяют поля в ответе.",
                    "type": "string"
                },
                "page": {
                    "required": false,
                    "default": 1,
                    "description": "Текущая страница коллекции.",
                    "type": "integer"
                },
                "per_page": {
                    "required": false,
                    "default": 10,
                    "description": "Максимальное число объектов возвращаемое в выборке.",
                    "type": "integer"
                },
                "search": {
                    "required": false,
                    "description": "Ограничить результаты до совпадающих со строкой.",
                    "type": "string"
                },
                "exclude": {
                    "required": false,
                    "default": [],
                    "description": "Убедиться что выборка исключает определенные ID.",
                    "type": "array",
                    "items": {
                        "type": "integer"
                    }
                },
                "include": {
                    "required": false,
                    "default": [],
                    "description": "Ограничить выборку до определенных ID.",
                    "type": "array",
                    "items": {
                        "type": "integer"
                    }
                },
                "order": {
                    "required": false,
                    "default": "asc",
                    "enum": [
                        "asc",
                        "desc"
                    ],
                    "description": "Упорядочить сортировку атрибута по возрастанию или убыванию.",
                    "type": "string"
                },
                "orderby": {
                    "required": false,
                    "default": "name",
                    "enum": [
                        "id",
                        "include",
                        "name",
                        "slug",
                        "include_slugs",
                        "term_group",
                        "description",
                        "count"
                    ],
                    "description": "Сортировать коллекцию по атрибутам элемента.",
                    "type": "string"
                },
                "hide_empty": {
                    "required": false,
                    "default": false,
                    "description": "Скрывать ли элементы не назначенные ни одной записи.",
                    "type": "boolean"
                },
                "parent": {
                    "required": false,
                    "description": "Ограничить выборку элементами назначенными определенному родителю.",
                    "type": "integer"
                },
                "post": {
                    "required": false,
                    "description": "Ограничить выборку элементами назначенными определенной записи.",
                    "type": "integer"
                },
                "slug": {
                    "required": false,
                    "description": "Ограничить выборку элементами с одним или более специальными ярлыками. ",
                    "type": "array",
                    "items": {
                        "type": "string"
                    }
                }
            }
        },
        {
            "methods": [
                "POST"
            ],
            "args": {
                "description": {
                    "required": false,
                    "description": "HTML описание элемента.",
                    "type": "string"
                },
                "name": {
                    "required": true,
                    "description": "HTML название элемента.",
                    "type": "string"
                },
                "slug": {
                    "required": false,
                    "description": "Буквенно-цифровой идентификатор элемента уникальный для его типа.",
                    "type": "string"
                },
                "parent": {
                    "required": false,
                    "description": "ID элемента родителя.",
                    "type": "integer"
                },
                "meta": {
                    "required": false,
                    "description": "Мета поля.",
                    "type": "object"
                }
            }
        }
    ],
    "schema": {
        "$schema": "http://json-schema.org/draft-04/schema#",
        "title": "category",
        "type": "object",
        "properties": {
            "id": {
                "description": "Уникальный идентификатор элемента.",
                "type": "integer",
                "context": [
                    "view",
                    "embed",
                    "edit"
                ],
                "readonly": true
            },
            "count": {
                "description": "Число опубликованных записей элемента.",
                "type": "integer",
                "context": [
                    "view",
                    "edit"
                ],
                "readonly": true
            },
            "description": {
                "description": "HTML описание элемента.",
                "type": "string",
                "context": [
                    "view",
                    "edit"
                ]
            },
            "link": {
                "description": "URL элемента.",
                "type": "string",
                "format": "uri",
                "context": [
                    "view",
                    "embed",
                    "edit"
                ],
                "readonly": true
            },
            "name": {
                "description": "HTML название элемента.",
                "type": "string",
                "context": [
                    "view",
                    "embed",
                    "edit"
                ],
                "required": true
            },
            "slug": {
                "description": "Буквенно-цифровой идентификатор элемента уникальный для его типа.",
                "type": "string",
                "context": [
                    "view",
                    "embed",
                    "edit"
                ]
            },
            "taxonomy": {
                "description": "Тип атрибуции элемента.",
                "type": "string",
                "enum": [
                    "category",
                    "post_tag",
                    "nav_menu",
                    "link_category",
                    "post_format"
                ],
                "context": [
                    "view",
                    "embed",
                    "edit"
                ],
                "readonly": true
            },
            "parent": {
                "description": "ID элемента родителя.",
                "type": "integer",
                "context": [
                    "view",
                    "edit"
                ]
            },
            "meta": {
                "description": "Мета поля.",
                "type": "object",
                "context": [
                    "view",
                    "edit"
                ],
                "properties": []
            }
        }
    },
    "_links": {
        "self": "http://wptest.ru/wp-json/wp/v2/categories"
    }
}

Список категорий

Получает список категорий, наподобие get_categories()

Вид запроса

GET /wp/v2/categories

Параметры запроса

context
Область, в которой выполняется запрос; определяет поля присутствующие в ответе.
Может быть: view, embed, edit
По умолчанию: view
page
Текущая страница пагинации.
По умолчанию: 1
per_page
Максимальное число элементов, возвращаемых в результате.
По умолчанию: 10
search
Ограничьте результаты теми, которые соответствуют строке.
exclude
Исключает рубрики по ID.
include
Показывает только указанные тут рубрики. Указывается ID.
orderby
По какому полю сортировать?
Может быть: id, include, name, slug, term_group, description, count
По умолчанию: name
order
Как сортировать?
Может быть: asc, desc
По умолчанию: asc
hide_empty
Спрятать ли пустые рубрики (где нет постов)?
parent
ID родительской рубрики, детей которых нужно получить.
post
ID поста, рубрики которого нужно получить.
slug
Укажите слаги рубрик которые нужно получить.

Пример запроса

http://demo.wp-api.org/wp-json/wp/v2/categories

Получим рубрики поста 1

http://demo.wp-api.org/wp-json/wp/v2/categories?post=1

Создание категории

Алгоритм схож с работой функции wp_insert_category()

Вид запроса

Доступ: нужна авторизация

POST /wp/v2/categories

Параметры запроса

name(обязательный)
Название термина (рубрики).
description
Описание термина (рубрики).
slug
Слаг (ярлык) термина (рубрики), обычно создается из названия.
parent
ID родительского термина.
meta
Мета поля.

Пример запроса:

POST http://example.com/wp-json/wp/v2/categories?name=Моя рубрика

Ответ

{
	"id": 6,
	"count": 0,
	"description": "",
	"link": "http://example.com/cat/%d0%bc%d0%be%d1%8f-%d1%80%d1%83%d0%b1%d1%80%d0%b8%d0%ba%d0%b0/",
	"name": "Моя рубрика",
	"slug": "%d0%bc%d0%be%d1%8f-%d1%80%d1%83%d0%b1%d1%80%d0%b8%d0%ba%d0%b0",
	"taxonomy": "category",
	"parent": 0,
	"meta": [],
	"_links": {
		"self": [
			{
				"href": "http://example.com/wp-json/wp/v2/categories/6"
			}
		],
		"collection": [
			{
				"href": "http://example.com/wp-json/wp/v2/categories"
			}
		],
		"about": [
			{
				"href": "http://example.com/wp-json/wp/v2/taxonomies/category"
			}
		],
		"wp:post_type": [
			{
				"href": "http://example.com/wp-json/wp/v2/posts?categories=6"
			}
		],
		"curies": [
			{
				"name": "wp",
				"href": "https://api.w.org/{rel}",
				"templated": true
			}
		]
	}
}

wp/v2/categories/{id}

Запрос OPTIONS к маршруту вернет полное описание этого маршрута: эндпоинты их параметры, схему.

$ curl -X OPTIONS -i http://demo.wp-api.org/wp-json/wp/v2/categories/1
GitHub
{
    "namespace": "wp/v2",
    "methods": [
        "GET",
        "POST",
        "PUT",
        "PATCH",
        "DELETE"
    ],
    "endpoints": [
        {
            "methods": [
                "GET"
            ],
            "args": {
                "id": {
                    "required": false,
                    "description": "Уникальный идентификатор элемента.",
                    "type": "integer"
                },
                "context": {
                    "required": false,
                    "default": "view",
                    "enum": [
                        "view",
                        "embed",
                        "edit"
                    ],
                    "description": "Рамки в которых сделан запрос, определяют поля в ответе.",
                    "type": "string"
                }
            }
        },
        {
            "methods": [
                "POST",
                "PUT",
                "PATCH"
            ],
            "args": {
                "id": {
                    "required": false,
                    "description": "Уникальный идентификатор элемента.",
                    "type": "integer"
                },
                "description": {
                    "required": false,
                    "description": "HTML описание элемента.",
                    "type": "string"
                },
                "name": {
                    "required": false,
                    "description": "HTML название элемента.",
                    "type": "string"
                },
                "slug": {
                    "required": false,
                    "description": "Буквенно-цифровой идентификатор элемента уникальный для его типа.",
                    "type": "string"
                },
                "parent": {
                    "required": false,
                    "description": "ID элемента родителя.",
                    "type": "integer"
                },
                "meta": {
                    "required": false,
                    "description": "Мета поля.",
                    "type": "object"
                }
            }
        },
        {
            "methods": [
                "DELETE"
            ],
            "args": {
                "id": {
                    "required": false,
                    "description": "Уникальный идентификатор элемента.",
                    "type": "integer"
                },
                "force": {
                    "required": false,
                    "default": false,
                    "description": "Должно быть истинно, так как элементы не поддерживают перемещение в корзину.",
                    "type": "boolean"
                }
            }
        }
    ],
    "schema": {
        "$schema": "http://json-schema.org/draft-04/schema#",
        "title": "category",
        "type": "object",
        "properties": {
            "id": {
                "description": "Уникальный идентификатор элемента.",
                "type": "integer",
                "context": [
                    "view",
                    "embed",
                    "edit"
                ],
                "readonly": true
            },
            "count": {
                "description": "Число опубликованных записей элемента.",
                "type": "integer",
                "context": [
                    "view",
                    "edit"
                ],
                "readonly": true
            },
            "description": {
                "description": "HTML описание элемента.",
                "type": "string",
                "context": [
                    "view",
                    "edit"
                ]
            },
            "link": {
                "description": "URL элемента.",
                "type": "string",
                "format": "uri",
                "context": [
                    "view",
                    "embed",
                    "edit"
                ],
                "readonly": true
            },
            "name": {
                "description": "HTML название элемента.",
                "type": "string",
                "context": [
                    "view",
                    "embed",
                    "edit"
                ],
                "required": true
            },
            "slug": {
                "description": "Буквенно-цифровой идентификатор элемента уникальный для его типа.",
                "type": "string",
                "context": [
                    "view",
                    "embed",
                    "edit"
                ]
            },
            "taxonomy": {
                "description": "Тип атрибуции элемента.",
                "type": "string",
                "enum": [
                    "category",
                    "post_tag",
                    "nav_menu",
                    "link_category",
                    "post_format"
                ],
                "context": [
                    "view",
                    "embed",
                    "edit"
                ],
                "readonly": true
            },
            "parent": {
                "description": "ID элемента родителя.",
                "type": "integer",
                "context": [
                    "view",
                    "edit"
                ]
            },
            "meta": {
                "description": "Мета поля.",
                "type": "object",
                "context": [
                    "view",
                    "edit"
                ],
                "properties": []
            }
        }
    }
}

Получение категории

Алгоритм схож с работой функции get_category().

Вид запроса

GET /wp/v2/categories/{id}

Параметры запроса

id(число)
Идентификатор термина.
context(строка)
Область, в которой выполняется запрос; определяет поля, присутствующие в ответе.
Может быть: view, embed, edit
По умолчанию: view

Пример запроса

http://demo.wp-api.org/wp-json/wp/v2/categories/25

Обновление категории

Алгоритм схож с работой функции wp_update_category()

Вид запроса

POST /wp/v2/categories/{id}

Параметры запроса

id(обязательный)
ID термина (рубрики).
name
Название термина (рубрики).
description
Описание термина (рубрики).
slug
Слаг (ярлык) термина (рубрики), обычно создается из названия.
parent
ID родительского термина.
meta
Мета поля.

Пример запроса

$ curl -X POST http://demo.wp-api.org/wp-json/wp/v2/categories/25 -d '{"name":"Новое имя"}'

Или

POST http://example.com/wp-json/wp/v2/categories/6?name=My rubrik&slug=My rubrik

Ответ

{
	"id": 6,
	"count": 0,
	"description": "",
	"link": "http://example.com/cat/my-rubrik/",
	"name": "My rubrik",
	"slug": "my-rubrik",
	"taxonomy": "category",
	"parent": 0,
	"meta": [],
	"_links": {
		"self": [
			{
				"href": "http://example.com/wp-json/wp/v2/categories/6"
			}
		],
		"collection": [
			{
				"href": "http://example.com/wp-json/wp/v2/categories"
			}
		],
		"about": [
			{
				"href": "http://example.com/wp-json/wp/v2/taxonomies/category"
			}
		],
		"wp:post_type": [
			{
				"href": "http://example.com/wp-json/wp/v2/posts?categories=6"
			}
		],
		"curies": [
			{
				"name": "wp",
				"href": "https://api.w.org/{rel}",
				"templated": true
			}
		]
	}
}

Удаление категории

Алгоритм схож с работой функции wp_delete_term()

Вид запроса

DELETE /wp/v2/categories/{id}

Параметры запроса

id(обязательный)
ID термина (рубрики).
force
Всегда должен быть true, так как термины не поддерживают корзину.

Пример запроса

$ curl -X DELETE http://example.com/wp-json/wp/v2/categories/6?force=true

Ответ

{
	"deleted": true,
	"previous": {
		"id": 6,
		"count": 0,
		"description": "",
		"link": "http://example.com/cat/my-rubrik/",
		"name": "My rubrik",
		"slug": "my-rubrik",
		"taxonomy": "category",
		"parent": 0,
		"meta": []
	}
}

Ответ если такой рубрики нет

{
	"code": "rest_term_invalid",
	"message": "Элемент не существует.",
	"data": {
		"status": 404
	}
}