WordPress.org

Make WordPress Core

Opened 5 months ago

Last modified 5 days ago

#47620 assigned feature request

REST API: Expose blocks registered on the server

Reported by: gziolo Owned by: spacedmonkey
Milestone: Future Release Priority: normal
Severity: normal Version: 5.0
Component: REST API Keywords: has-patch has-unit-tests dev-feedback
Focuses: rest-api Cc:
PR Number:

Description (last modified by gziolo)

Related post:

https://make.wordpress.org/core/2019/05/27/the-block-registration-api-status-update/

Related GitHub issue:

https://github.com/WordPress/gutenberg/issues/2751

Related Block Registration API technical proposal with all the necessary details is available at:

https://github.com/WordPress/gutenberg/blob/master/docs/rfc/block-registration.md

The long term vision for the block discovery in WordPress includes:

  • Fetching the available block types through REST APIs.
  • Fetching block objects from posts through REST APIs.

There is no immediate need to start working on new block type related API endpoints. However, it would be great to have it included on the roadmap. Ideally, they should stay as close as possible to the WordPress.org API and the final shape of the endpoint for searching for blocks. This is going to be introduced as part of the Block Directory project.

Attachments (2)

47620.diff (12.0 KB) - added by spacedmonkey 4 weeks ago.
47620.2.diff (12.1 KB) - added by spacedmonkey 4 weeks ago.

Download all attachments as: .zip

Change History (24)

#1 @gziolo
5 months ago

  • Description modified (diff)

#2 @SergeyBiryukov
5 months ago

  • Component changed from General to Editor

#3 follow-up: @spacedmonkey
5 months ago

  • Component changed from Editor to REST API
  • Version set to 5.0

Thanks for the ticket @gziolo .

I have some questions.

  • What fields should be exposed in the api?
  • What permissions should be required to access this fields?
  • What filter is required? Filter by namespace? Filter by full name? Is search required?

Can someone loop someone from the mobile team into this ticket to give feedback.

CC @aduth

@spacedmonkey
4 weeks ago

#5 @spacedmonkey
4 weeks ago

  • Keywords has-patch has-unit-tests dev-feedback added
  • Owner set to spacedmonkey
  • Status changed from new to assigned

I have created a first pass of the api in 47620.diff.

I have added the ability to filter name a block's namespace. Not sure if this is required, but seems like a nice feature.

I think this can land in WP 5.4. Thoughts @kadamwhite @TimothyBlynJacobs ?

#6 @TimothyBlynJacobs
4 weeks ago

Just a bit of quick feedback, I think we should only have one get_item route instead of registering a new rest route for each block.

This ticket was mentioned in Slack in #core-restapi by spacedmonkey. View the logs.


4 weeks ago

This ticket was mentioned in Slack in #core-editor by spacedmonkey. View the logs.


4 weeks ago

#9 in reply to: ↑ 3 @gziolo
4 weeks ago

  • What fields should be exposed in the api?

You can see the full Block API which should be exposed to the client in https://github.com/WordPress/gutenberg/blob/master/docs/rfc/block-registration.md#block-api.

The gist of it is presented in the following example:

{
	"name": "my-plugin/notice",
	"title": "Notice",
	"category": "common",
	"parent": [ "core/group" ],
	"icon": "star",
	"description": "Shows warning, error or success notices  ...",
	"keywords": [ "alert", "message" ],
	"textDomain": "my-plugin",
	"attributes": {
		"message": {
			"type": "string",
			"source": "html",
			"selector": ".message"
		}
	},
	"styleVariations": [ 
		{ "name": "default", "label": "Default", "isDefault": true }, 
		{ "name": "other", "label": "Other" }
	],
	"editorScript": "build/editor.js",
	"script": "build/main.js",
	"editorStyle": "build/editor.css",
	"style": "build/style.css"
}

I think some of the fields are missing in your initial diff.

What permissions should be required to access this fields?

That's a great question. I don't know myself. I can share for reference the implementation of the endpoint for the Block Directory:
https://github.com/WordPress/gutenberg/blob/b138818dd4860151eb345606b1396a198572aefa/lib/class-wp-rest-block-directory-controller.php#L76-L85

It doesn't look like it checks the permission for accessing blocks. /cc @tellyworth

@spacedmonkey
4 weeks ago

#10 follow-up: @spacedmonkey
4 weeks ago

Just a bit of quick feedback, I think we should only have one get_item route instead of registering a new rest route for each block.

Thanks for the feedback at @TimothyBlynJacobs . I have updated the patch to not do this anymore see 47620.2.diff.

What permissions should be required to access this fields?

Current my patch uses edit_posts cap. This api should be available to everyone that can edit a post, if it is to be used in the mobile app. install_plugins cap is very limiting as by default only administrators have this cap.

As for the missing fields @gziolo , I wasn't sure of the state of the RFC, so didn't review it. Can we use this a design for the API?

Currently the API lists off a list of WP_Block_Type objects, the definition of which can we found here. But this class only has the following properties.

  • name
  • render_callback
  • attributes
  • editor_script
  • script
  • editor_style
  • style

The classes doesn't allow for other fields. So these would have to be added to the class. This is not a small change, as it would require the updating of the docs / unit tests / implementation of the register_block_type function. This should likely happen in another ticket, as this is a sizale change.

Reviewing the document, it seems like the missing fields are.

  • title
  • category
  • parent
  • icon
  • description
  • keywords
  • textDomain
  • styleVariations

But I would also recommend adding

  • supports

I would also look at the newly added

  • example

Also where is the URL for translations defined?

Last edited 4 weeks ago by spacedmonkey (previous) (diff)

#11 in reply to: ↑ 10 @gziolo
4 weeks ago

Replying to spacedmonkey:

Current my patch uses edit_posts cap. This api should be available to everyone that can edit a post, if it is to be used in the mobile app. install_plugins cap is very limiting as by default only administrators have this cap.

It's a different use case for the Block Directory, my point was that it doesn't use any other permission check there. This is something that should be addressed in both places.

As for the missing fields @gziolo , I wasn't sure of the state of the RFC, so didn't review it. Can we use this a design for the API?

It's based on the actual implementation in Gutenberg for core blocks and the Block Directory also follows the same API.

The classes doesn't allow for other fields. So these would have to be added to the class. This is not a small change, as it would require the updating of the docs / unit tests / implementation of the register_block_type function. This should likely happen in another ticket, as this is a sizale change.

It's a fair point. You can split work into two parts, whatever other reviewers feel is the best. To make it functional though, we need to have all those additional fields covered because we won't be able to integrate this new endpoint with the block editor on the client-side.

But I would also recommend adding

  • supports

We plan to deprecate this field. In the long run, we want to provide a more robust API to achieve the same goal. It would be nice to skip this field from the REST API. We keep this field on the client for all core blocks.

I would also look at the newly added

  • example

Yes, this one might be a good fit as well. We should double-check first whether the format provided can be encoded in JSON files.

Also where is the URL for translations defined?

Can you explain what is this about? Maybe @swissspidy will know :)

This ticket was mentioned in Slack in #core-editor by gziolo. View the logs.


4 weeks ago

#13 @spacedmonkey
4 weeks ago

  • Milestone changed from Awaiting Review to Future Release

#14 @spacedmonkey
4 weeks ago

I have broken the work to add the extra fields into another ticket.

#15 @spacedmonkey
3 weeks ago

In the RFC, editor_script, script, editor_style and style are defines as URLs. However PHP registered block use script / style handles. See wp_enqueue_registered_block_scripts_and_styles.
The wp_enqueue_style and wp_enqueue_script can not currently handle passing a url to them.

TL:DR If you pass a URL in editor_script, script, editor_style and style fields, is not going to work and may break things.

Also looking into this, I believe it is pointless to just output the url / handle of the script. Without the dependencies, inline scripts, translations and localized, the script is unless. So maybe we either need to add all this data into the API or we need another REST API for this. Thoughts @gziolo ?

This ticket was mentioned in Slack in #core-restapi by spacedmonkey. View the logs.


3 weeks ago

#17 @gziolo
3 weeks ago

@spacedmonkey, this path to the script or the style isn't very useful on its own, see the full description:

https://github.com/WordPress/gutenberg/blob/master/docs/rfc/block-registration.md#WPDefinedAsset

in addition @youknowriad opened this ticket which perfectly fits to your question:

https://core.trac.wordpress.org/ticket/48654

This asset handling is the most complex part of the block definition but we need it to be able to (lazy) load blocks on demand in the client.

#18 @spacedmonkey
2 weeks ago

As discussed in the REST API meeting, it makes sense to handle script and styles in another REST API. This is different data. Also a scripts and styles API has other uses, such as lazy loading.

Let's keep just the handles in this API for now, and move the discussion of scripts / styles into #48654

#19 @gziolo
2 weeks ago

I missed the chat but I echo what you shared. It makes a lot of sense to split this task into smaller parts to focus on what's already well defined.

#20 @spacedmonkey
2 weeks ago

The WPDefinedAsset object isn't specially useful. It doesn't allow a user to get a list of dependencies, localisation and translations, meaning it wouldn't work well for mobile app or lazying loading blocks. This why that work has moved to #48654 where the security issues can be discussed in more detail.

#21 @koke
10 days ago

Have we considered adding block versions to the API? We've already encountered some issues in the past where there was a mismatch between the version of the block shipping with the apps and the one in the server. A version number doesn't solve the whole problem of backwards and forwards compatibility, but at least can help detect and notify the user better if they need to update something.

#22 @koke
5 days ago

To clarify the mobile perspective, we are currently not loading any code from the server. We have doubts that the App Store Guidelines would allow us to do so. The current approach is that we are shipping the code for the core blocks we support with the apps. Once we have enough to support plugins, the idea is to start doing the same for the most popular/requested plugins and ship their code alongside the apps.

That's why we need a version to know which code matches to a specific block. We have already run into issues with that recently. Whenever a block markup changes, Gutenberg is designed to deal with backwards compatibility and migrate that content automatically. However, it might be the case that you try to open a block created with the newer markup with an older client, leading to "invalid content".

This can happen both ways: people might upgrade their site before their apps, but also we are currently developing gutenberg-mobile against master, so users would get updated on mobile way before they do on their sites, unless they are running the plugin.

Note: See TracTickets for help on using tickets.