Jonny Harris 11:37 am on January 24, 2022
Tags: , ,   

Menus endpoints in WordPress 5.9

WordPress 5.9 adds three new REST APIREST API The REST API is an acronym for the RESTful Application Program Interface (API) that uses HTTP requests to GET, PUT, POST and DELETE data. It is how the front end of an application (think “phone app” or “website”) can communicate with the data store (think “database” or “file system”) https://developer.wordpress.org/rest-api/. endpoints to manage menus and menu locations. These menus endpoints are used the in new navigation block.

The new Navigation block

Before discussing menu endpoints, it’s worth noting how menus are currently stored. Navigation menus are stored using the nav_menu taxonomyTaxonomy A taxonomy is a way to group things together. In WordPress, some common taxonomies are category, link, tag, or post format. https://codex.wordpress.org/Taxonomies#Default_Taxonomies. and the nav_menu_item post type. A menu is stored as a term and acts like a container for a number of menu items. Menu items are stored as posts. Menus and menu items also have custom fields stored in metaMeta Meta is a term that refers to the inside workings of a group. For us, this is the team that works on internal WordPress sites like WordCamp Central and Make WordPress. and in various options.

Accessible via /wp/v2/menus, the menus endpoint allows for performing CRUDCRUD Create, read, update and delete, the four basic functions of storing data. (More on Wikipedia.) operations on menu data. This endpoint extends the WP_REST_Terms_Controller class, mapping fields to the menus and adding functionality like auto_add, that automatically adds new pages to menus when created. A GET request includes the list of menus, but does not contain the list of menu items. To get this data, the menu items endpoint can be used.

Example output from request:

{
    "auto_add": false
    "description": "",
    "id": 36,
    "locations": ['wporg_header_subsite_nav', 'primary'],
    "meta": [],
    "name": "Navigation",
    "slug": "navigation",
}

Accessible via /wp/v2/menu-items, the menu items endpoint allows for performing CRUD operations on menu items and assigning them to menus. This endpoint extends the WP_REST_Posts_Controller class, mapping fields and adding custom functionality. Menu items can only be assigned to one menu at a time unlike other taxonomies.

Many menu items have an associated object that the menu item links to. For instance, a link to a page will have the object set to page and the object_id set to the WordPress Post ID of that page. When using this endpoint, it may be useful to get information about that linked object. For example the page’s title. This information is not included in the response by default, but the REST API has a feature to embed this information by using the _embed query parameter. For example, making a GET request to /wp/v2/menu-item/8874?_embed=true will result in the following response:

{
     "attr_title": "",
     "classes": [''],
     "description": "",
     "id": 8874,
     "invalid": false,
     "menu_order": 1,
     "menus": 363,
     "meta": {},
     "object": "page",
     "object_id": 8823,
     "parent": 0,
     "status": "publish",
     "target": "",
     "title": {rendered: 'Tickets'},
     "type": "post_type",
     "type_label": "Page",
     "url": "https://make.wordpress.org/core/reports/",
     "xfn": [""],
     "_embedded": {
              wp:menu-item-object: [
                   {
                      "author": 5286302,
                      "date": "2014-01-29T19:49:26",
                      "featured_media": 0,
                      "id": 8823,
                      "link": "https://make.wordpress.org/core/reports/",
                      "slug": "reports",
                      "title": { "rendered": "Bug Reports"},
                      "type": "page",
                   }
              ],
              wp:term: [
                    {
                       "id": 363,
                       "name": "Navigation",
                       "slug": "navigation"
                    }
              ]
    },
}

Accessible via /wp/v2/menu-locations, the menu locations endpoint returns a list of menu locations registered with the register_nav_menus function. To assign a menu to a particular location, use the menus endpoint, by passing an array of menu location keys.

Example output from request:

{
     "description": "Desktop Horizontal Menu"
     "menu": 90
     "name": "primary"
}

Batching requests

Both the menu and menu item endpoints, both support the batching of requests, introduced in WordPress 5.6. This means that more than one menu / menu item can be updates / created in a simple request to the APIAPI An API or Application Programming Interface is a software intermediary that allows programs to interact with each other and share data in limited, clearly defined ways..

Access Control

To access data from any of the menus endpoints, requests must be made by a logged in user with the edit_theme_options capability. By default, only users with the Administrator role have this capability. This means that menu data is not publically exposed via the REST API. Ticketticket Created for both bug reports and feature development on the bug tracker. #54304 provides a means for developers to opt-in to exposing this data publicly. The REST API team hopes to implement this feature in a near future release of WordPress.

These endpoints were first developed as a feature pluginFeature Plugin A plugin that was created with the intention of eventually being proposed for inclusion in WordPress Core. See Features as Plugins. on GitHub. For those using this pluginPlugin A plugin is a piece of software containing a group of functions that can be added to a WordPress website. They can extend functionality or add new features to your WordPress websites. WordPress plugins are written in the PHP programming language and integrate seamlessly with WordPress. These can be free in the WordPress.org Plugin Directory https://wordpress.org/plugins/ or can be cost-based plugin from a third-party, after upgrading to WordPress 5.9, the plugin can be deactivated and removed as all of it’s functionality is now included in WordPress CoreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress..

Props to @timothyblynjacobs for peer review.

#5-9, #dev-notes, #rest-api