Справочник: меню
Ручки сайта: $API/site/$SITE/menus…. Чтение пунктов — источник GET /data/menu.<область>. {ref} меню — id, слаг, имя или область с тильдой (~header, также принимается @header). Во всех ручках, где есть lang, он выбирает меню языка (для ~область) или карту Polylang; theme — писать в карту областей другой темы. Как устроены меню — меню.
Каждая запись (кроме PATCH /menus/{ref}) пересобирает фреймы с меню и сбрасывает кэш их страниц — поле rebaked.
Пункт в теле: {"page": id|слаг|путь} или {"url": "…"}, плюс title, target, classes (строка через пробел), children (массив пунктов), parent (id пункта-родителя — при добавлении одного). Голое значение — ссылка на страницу. Путь в url дополняется адресом сайта.
GET /menus
curl -s -H "Authorization: Bearer $OP_TOKEN" "$API/site/$SITE/menus"{
"success": true,
"site_id": "x9HTLHECq",
"theme": "onpress-v2",
"locations": ["header", "footer_1", "footer_2", "footer_3"],
"default_lang": "en",
"read_items_at": "/data/menu.{location}",
"total": 14,
"menus": [
{ "id": 83, "name": "header en", "slug": "header-en", "items": 3, "assigned": [ { "location": "header", "lang": "en" } ] },
{ "id": 87, "name": "footer center en", "slug": "footer-center-en", "items": 9, "assigned": [] }
]
}Параметр theme — прочитать карту областей другой темы.
POST /menus
| Поле | Смысл |
|---|---|
name | обязательно |
slug | по умолчанию из имени, делается уникальным |
location | сразу поставить в область |
lang | язык для карты Polylang |
items | сразу наполнить деревом |
allow_invalid | пропустить пункты на неопубликованные страницы |
theme | тема для карты областей |
curl -s -X POST "$API/site/$SITE/menus" \
-H "Authorization: Bearer $OP_TOKEN" -H 'Content-Type: application/json' \
-d '{"name": "Проба меню", "slug": "docs-proba-menu", "items": [{"page": "proba-api", "title": "Проба"}, {"url": "https://onpress.pro/", "title": "OnPress", "target": "_blank", "classes": "btn btn--primary", "children": [{"page": "/proba-lending/"}]}]}'{
"success": true,
"site_id": "x9HTLHECq",
"theme": null,
"menu": { "id": 171, "name": "Проба меню", "slug": "docs-proba-menu", "items": 3 },
"items": [
{ "id": 6433, "at": "0", "title": "Проба", "type": "post_type", "page": 6428, "url": "/proba-api/", "parent": 0, "order": 1, "valid": true },
{ "id": 6434, "at": "1", "title": "OnPress", "type": "custom", "page": null, "url": "https://onpress.pro/", "parent": 0, "order": 2, "valid": true },
{ "id": 6435, "at": "1.0", "title": "Лендинг-проба", "type": "post_type", "page": 6432, "url": "/proba-lending/", "parent": 6434, "order": 3, "valid": true }
],
"invalid": [],
"rebaked": { "status": "ok", "total": 9, "…": "…" }
}at — координата пункта в присланном дереве ("1.0" — первый ребёнок второго). Отказы: 400 menu_name_required, 400 bad_items, 400 unknown_location, 400 unknown_language, 409 polylang_inactive, 409 menu_items_unresolved (errors), 409 menu_items_invalid (invalid), 500 menu_assignment_not_stored.
PATCH /menus/{ref}
Переименовать: name и/или slug (уникальный среди меню). Пункты и области не трогаются.
curl -s -X PATCH "$API/site/$SITE/menus/docs-proba-menu" \
-H "Authorization: Bearer $OP_TOKEN" -H 'Content-Type: application/json' -d '{"name": "Проба меню 2"}'{ "success": true, "site_id": "x9HTLHECq", "menu": { "id": 171, "term_taxonomy_id": 171, "name": "Проба меню 2", "slug": "docs-proba-menu", "count": 4 } }Отказы: 400 nothing_to_update, 404 menu_not_found, 409 ambiguous_menu.
DELETE /menus/{ref}
Удалить меню со всеми пунктами и освободить его области (в карте темы и в карте Polylang).
{ "success": true, "site_id": "x9HTLHECq", "deleted": { "id": 171, "name": "Проба меню 2", "slug": "docs-proba-menu" }, "removed_items": 2, "freed_locations": [] }PUT /menus/{ref}/location
| Поле | Смысл |
|---|---|
location | обязательно: header, footer_1, footer_2, footer_3 |
lang | язык; без него или с основным пишется и карта темы |
theme | тема для карты областей |
Записанные карты перечитываются и сверяются. Отказы: 400 location_required (в том числе пустая строка — снять меню с области этой ручкой нельзя), 400 unknown_location (locations), 400 unknown_language, 409 polylang_inactive, 500 menu_assignment_not_stored (read_back), 404 menu_not_found.
PUT /menus/{ref}/items
Положить дерево пунктов целиком.
| Поле | Смысл |
|---|---|
items | обязательно: дерево пунктов |
allow_invalid | пропустить пункты на неопубликованные страницы |
lang, theme | для ~область |
curl -s -X PUT "$API/site/$SITE/menus/171/items" \
-H "Authorization: Bearer $OP_TOKEN" -H 'Content-Type: application/json' \
-d '{"items": [{"page": "proba-api"}, {"url": "/docs/", "title": "Документация"}]}'{
"success": true,
"site_id": "x9HTLHECq",
"menu": { "id": 171, "name": "Проба меню 2", "slug": "docs-proba-menu" },
"total": 2,
"invalid": [],
"items": [
{ "id": 6437, "at": "0", "title": "Проба API", "type": "post_type", "page": 6428, "url": "/proba-api/", "parent": 0, "order": 1, "valid": true },
{ "id": 6438, "at": "1", "title": "Документация", "type": "custom", "page": null, "url": "https://test.onpress.pro/docs/", "parent": 0, "order": 2, "valid": true }
],
"read_items_at": "/data/menu.{location}",
"rebaked": { "…": "…" }
}Отказы: 400 bad_items, 409 menu_items_unresolved, 409 menu_items_invalid, 404 menu_not_found, 404 menu_not_assigned (для ~область без меню).
POST /menus/{ref}/items
Добавить один пункт в конец уровня (parent — к родителю). Тело — {"item": {…}} или сам пункт.
curl -s -X POST "$API/site/$SITE/menus/171/items" \
-H "Authorization: Bearer $OP_TOKEN" -H 'Content-Type: application/json' -d '{"item": {"page": "docs", "title": "Доки"}}'{ "success": true, "site_id": "x9HTLHECq", "menu": { "id": 171, "name": "Проба меню" }, "item": { "id": 6436, "title": "Доки", "type": "post_type", "page": 6183, "url": "/docs/", "parent": 0, "order": 4, "valid": true }, "total": 4 }Отказы: 400 item_target_required, 404 page_not_found, 409 menu_items_invalid, 404 item_not_found (родитель).
PATCH /menus/{ref}/items/{id}
Поля: title, page, url, target, classes, parent. page превращает пункт в пункт-страницу, url — в ссылку.
{ "success": true, "site_id": "x9HTLHECq", "menu": { "id": 171, "name": "Проба меню 2" }, "item": { "id": 6434, "title": { "from": "OnPress", "to": "OnPress.pro" }, "url": "https://onpress.pro/docs/" }, "warnings": [] }Отказы: 404 item_not_found, 409 bad_parent (пункт сам себе родитель), 404 page_not_found, 409 menu_items_invalid.
DELETE /menus/{ref}/items/{id}
Удалить пункт вместе с веткой.
{ "success": true, "site_id": "x9HTLHECq", "menu": { "id": 171, "name": "Проба меню 2" }, "removed": [6434, 6435], "total": 2 }POST /menus/{ref}/reorder
| Поле | Смысл |
|---|---|
order | обязательно: id пунктов уровня в нужном порядке |
parent | id родителя уровня, 0 — верхний (по умолчанию) |
{ "success": true, "site_id": "x9HTLHECq", "menu": { "id": 171, "name": "Проба меню 2" }, "parent": 0, "order": [6436, 6433, 6434], "appended": [6434] }Неназванные пункты уровня встают после названных (appended). Отказы: 400 bad_reorder, 404 item_not_found.