REST API: Introduce dashboard namespace

Welcome!

The WordPress coreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. development team builds WordPress! Follow this site for general updates, status reports, and the occasional code debate. There’s lots of ways to contribute:

Found a bugbug A bug is an error or unexpected result. Performance improvements, code optimization, and are considered enhancements, not defects. After feature freeze, only bugs are dealt with, with regressions (adverse changes from the previous version) being the highest priority.? Create a ticket in the bug tracker.

Want to contribute? Get started quickly with tickets marked as good first bugs for new contributors or join a bug scrub. There’s more on the reports page, like patches needing testing, and on feature projects page.

Other questions? Here is a detailed handbook for contributors, complete with tutorials.

Summary

We propose to introduce a dashboard 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/. namespace prefix, for use on endpoints specifically relating to the WordPress adminadmin (and super admin) dashboard.

Motivation

WordPress coreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. currently contains two namespace prefixes: wp and oembed. These represent two separate APIs offered by WordPress: the general REST API which exposes structured WordPress data objects to external clients, and the OEmbed implementation.

The general design of WordPress distinguishes between the core, and the Dashboard “application” built on top of it. These two have not traditionally been formally separated, however the design and clean slate of the REST API allows us to consider these separately as we evolve the Dashboard.

With the push towards removing admin-ajax handlers in favour of new REST API endpoints, there are naturally 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. endpoints being introduced which are not useful outside of the administrative interface. Endpoints for Dashboard Widgets, pointers, and other features are specific to the Dashboard application, and are not broadly applicable to public-facing WordPress sites or third-party applications.

Introducing a new dashboard namespace prefix allows separating Dashboard-specific endpoints from the public WordPress REST API. This can also allow for future changes, deprecations, and new versions of the Dashboard API without requiring a version bump for the public REST API.

Detailed design

New endpoints for the Dashboard will live under dashboard/, initially with the namespace dashboard/v1 for the first version of endpoints.

Future iterations of the Dashboard that need to break API backwards compatibility can increment the version under the same namespace prefix as needed (e.g. dashboard/v2, dashboard/v3). These new versions do not need to affect the public WordPress REST API.

This requires no code changes, as it simply designates the namespace for future use. The first endpoints to be added under this new namespace are expected to be the endpoints for Site Health (#48105) in WordPress 5.4.

How do we communicate this?

The new endpoints under the dashboard namespace prefix will collectively be called the Dashboard REST API to distinguish them from the public WordPress REST API.

There are no user-facing changes resulting from this proposal. Likewise, there is no effect on 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, theme, or API client developers.

The difference between wp and dashboard needs to be communicated to core developers working on the Dashboard and related features. The announcement of this RFC on the Make/Core blogblog (versus network, site) will serve as an initial announcement, but evergreen documentation should be added to the Core Handbook.

A new page will be added to the REST API Handbook under the “Best Practices” section, outlining design guidelines for new endpoints added to WordPress Core. The proposed text for this page is:

REST API

Core implementations of REST API endpoints should follow some simple rules to ensure WordPress provides a consistent public data interface.

Creating New Endpoints

Where possible, core features should use existing REST API endpoints rather than adding new ones. For example, a tagtag A directory in Subversion. WordPress uses tags to store a single snapshot of a version (3.6, 3.6.1, etc.), the common convention of tags in version control systems. (Not to be confused with post tags.) search feature should use the existing tag collection endpoint in the REST API rather than building one specifically for the feature.

When a new endpoint is required, care should be put into the design of the external API. In particular, the shape and schema of the resource, the namespace, the route (URLURL A specific web address of a website or web page on the Internet, such as a website’s URL www.wordpress.org), and the available actions should match existing precedent in core.

REST API endpoints intended for public use and which represent “core” features of WordPress should be under the public REST API namespace (wp/v2). Endpoints which are only applicable for the Dashboard (e.g. Dashboard Widgets, pointers, or other UIUI User interface settings) should be under the Dashboard REST API namespace (dashboard/v1). This ensures a clear distinction between APIs for general consumption and APIs built for specific UI features.

The design and implementation of the endpoint can be checked by the REST API team before committing to ensure it is consistent with the rest of the API. This helps us provide a more consistent experience for API consumers.

Drawbacks

Introducing a new core namespace could impact third-party plugins or other code which uses the same namespace string. This represents a minor backwards compatibility break, and investigation needs to be done as to whether we’re breaking any major plugins with this change.

It could also be argued that it fragments core’s API surface to introduce an entirely new namespace. Making the distinction of which namespace to use is tough, and this might lead to features that could have general applicability existing only as part of the Dashboard API, without a public API for use by external clients.

In addition, adding a new namespace opens the question of whether more even namespaces are needed. For example, should there be a CustomizerCustomizer Tool built into WordPress core that hooks into most modern themes. You can use it to preview and modify many of your site’s appearance settings. namespace? Do other features need their own namespaces as well?

Alternatives

There are a few main alternatives to creating a dashboard namespace prefix.

The first is to use the current wp/v2 namespace for endpoints relating to administrative interfaces like Site Health. The main reason to avoid doing this is that it couples Dashboard-specific features to the public REST API. These features are rarely applicable or usable outside of the Dashboard application, especially in third-party plugin interfaces or external clients. In addition, this would also tie Dashboard API versioning to the public REST API, which could lead to the public REST API version being needlessly bumped for Dashboard-only changes.

Another alternative is to use a sub-namespace prefix of the existing wp prefix, such as wp/dashboard. This avoids any risk of impacting existing plugins as wp is already known to be reserved for core. However, this breaks the current precedent of <prefix>/v<version>, increasing the complexity of API namespacing. Given that it is unlikely that the dashboard prefix is currently being used, the simpler option of dashboard/v1 is preferred. This also discourages a proliferation of sub-namespaces under the wp prefix.

The final alternative is creating a separate namespace for each feature, such as site-health/v1. This could have the advantage of making endpoints more discoverable, and would reduce the overall length of each endpoint’s URIs. A dashboard prefix may also imply that its endpoints are “private” to WordPress and specific to the WordPress display context in cases where future endpoints may be useful in third-party tools. This approach has the disadvantage that plugin developers may worry that any namespace they pick could eventually be reappropriated by WordPress core.

Unresolved Questions

Should we use admin/v1 or dashboard/v1? To some dashboard is unclear and meaningless, to others admin is very specific to wp-admin whereas dashboard is more general idea of management.
Should we use dashboard/v1 or wp/dashboard/v1? The former could potentially clash with plugins, and is much more generic. We also need to pave the way for further namespaces that may be added to core in the future, where clashes may be more common.

Originally written by @rmccue as a WP-API Proposal.

#5-4, #rest-api, #site-health

Joy 6:24 pm on January 31, 2020

Why not `wpdashboard/` instead? That way it wouldn’t affect any plugins.
- Timothy Jacobs 9:25 pm on January 31, 2020
  
  That’d be a possibility, though I think I’d prefer wp-dashboard in that case.
  
  WPDirectory.net is down which makes it difficult, but we could check if any published plugins are using the dashboard prefix.
  - Peter Wilson 4:46 am on February 1, 2020
    
    I’d be inclined toward wp-dashboard myself to match the prefixing used by CoreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress.’s database tables, functions, etc, etc.
    
    As you say, this presumes it’s not in use by a wildly popular 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.
Michael Nelson 6:34 pm on January 31, 2020

If you can imagine a world with different adminadmin (and super admin) dashboards (I suppose you don’t need to imagine too much, there was already calypso for WP.com, mobile apps, and I think desktop apps) having endpoints specific to the existing WPdashboard located in the “dashboard” namespace makes sense (and things that could be used by other interfaces located in “wp” namespace.)
However, site health seems like something that could be used by other interfaces and so shouldn’t go into the “dashboard” namespace.
What other endpoints might “dashboard” contain?
- Timothy Jacobs 9:35 pm on January 31, 2020
  
  Do you think it’d be strange for those alternative interfaces to be using dashboard endpoints? For instance, I think it’d be fine if a hosting company that wanted to surface this information in their control panel (or elsewhere) used dashboard endpoints.
Dominik Schilling 6:49 pm on January 31, 2020

Wondering if wp-site-health/v1, wp-customize/v1, etc. would be an option too? Basically any component prefixed with wp-.
- Timothy Jacobs 9:27 pm on January 31, 2020
  
  I think that’d be an option as well. Do you think that Site Health is large enough to justify it being its own dedicated namespace.
- K. Adam White 2:32 am on February 1, 2020
  
  This is basically the option Timothy outlines in the “final alternative” section above. I’m opposed on the grounds that it leads to coreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. being in the future able to, and on track to, introduce a large number of top level namespaces for disparate features, which would be to my mind both unwieldy and unkind to 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 developers who won’t have any assurance the namespaces they pick will remain their own. I’d rather have wp/* remain the endpoint for “data within your site,” and to have a single “dashboard” or (actually my preference) a more generic “adminadmin (and super admin)” or “site” endpoint relating to higher order system information, health, maintenance and administration independent of a specific type of data. I would definitely assume that, with the proper authentication, plugins or alternative dashboards like Calypso (or full-site GutenbergGutenberg The Gutenberg project is the new Editor Interface for WordPress. The editor improves the process and experience of creating new content, making writing rich content much simpler. It uses ‘blocks’ to add richness rather than shortcodes, custom HTML etc. https://wordpress.org/gutenberg/, more pertinently) would be able to utilize this new namespace when required.
  
  Edit: I didn’t see your prefix comment, of course that obviates the namespace-squatting concern. But I think the generality of a prefix free namespace is nice given how much we’ve tried to get away from WP prefixes in 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. to date.
rheinardkorf 7:40 am on February 1, 2020

I would also like to add my preference for `wp/*` sub-namespaces. The biggest concern is as 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 developers keep on adding their own endpoints that it’s impossible for developers to know which namespaces to avoid. Keeping within the `wp/*` namespace also makes it obvious that we are dealing with coreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. endpoints and that we can trust they will be there when we need them. (Whereas third-parties can change their namespaces or remove APIs… core is more, for lack of better term, trustworthy).
apedog 6:59 pm on April 19, 2020

+1 for admin namespace. To me dashboard means that one specific page at the top of the adminadmin (and super admin)/backend menu that I never use. While admin suggests the more general concept of administration.

Also, “dashboard”/”application dashboard” suggests a specific visual layout UIUI User interface. A lot of applications have an administration dashboard, so it’s understood that the dashboard is where one can fiddle with different settings. But the concept of a dashboard has very visual connotations. Things are layed-out on a dashboard.

It’s counter-intuitive to think of a data 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. as a layout/dashboard.

Comments are closed.