Add reusable blocks REST API

[noisysocks]

Baby's first PR! 👶

This adds the REST API for creating, viewing and editing reusable blocks that @westonruter described in #2081. This API will let us add the ability to turn a static block into a dynamic reusable block (see #1516).

What I did

The TL;DR of it all is:

• I'm adding a new post type named gb_reusable_block
• I'm adding three REST API endpoints:
  • GET /wp-json/gutenberg/v1/reusable-blocks - lists all reusable blocks
  • GET /wp-json/gutenberg/v1/reusable-blocks/:uuid - fetches a single reusable block
  • PUT /wp-json/gutenberg/v1/reusable-blocks/:uuid - creates or edits a reusable block
• A reusable block looks like this:

  {
    "id": "358b59ee-bab3-4d6f-8445-e8c6971a5605",
    "name": "My cool block",
    "content": "<!-- wp:core/paragraph -->\n<p>Hello <strong>World</strong>! How are you?</p>\n<!-- /wp:core/paragraph -->"
  }

  They're stored as posts with post_type set to gb_reusable_block.
  • id is stored in post_name
  • name is stored in post_title
  • content is stored in post_content

How to test

OK. First, make sure you have the JSON Basic Authentication plugin installed, and that your test WordPress environment has pretty URLs enabled.

Now, you can create a block by hitting the PUT endpoint:

$ curl -v -X PUT --user admin:password -H 'Content-type: application/json' -d '{"content":"<!-- wp:core/paragraph -->\n<p>Hello!</p>\n<!-- /wp:core/paragraph -->","name":"My cool block"}' http://vagrant.local/wp-json/gutenberg/v1/reusable-blocks/358b59ee-bab3-4d6f-8445-e8c6971a5605

You'll likely want to change admin:password and http://vagrant.local to match your test WordPress environment.

Now that our block is created, we can fetch it:

$ curl --user admin:password http://vagrant.local/wp-json/gutenberg/v1/reusable-blocks/358b59ee-bab3-4d6f-8445-e8c6971a5605
{"id":"358b59ee-bab3-4d6f-8445-e8c6971a5605","name":"My cool block","content":"<!-- wp:core/paragraph -->\n<p>Hello!</p>\n<!-- /wp:core/paragraph -->"}

We can also list all blocks:

$ curl --user admin:password http://vagrant.local/wp-json/gutenberg/v1/reusable-blocks
[{"id":"358b59ee-bab3-4d6f-8445-e8c6971a5605","name":"My cool block","content":"<!-- wp:core/paragraph -->\n<p>Hello!</p>\n<!-- /wp:core/paragraph -->"}]

Play around with creating, editing and reading a few different valid and invalid reusable blocks.

---

cc. @nb @mtias @westonruter

[noisysocks]

For context, I'm working on building out the flow that @jasmussen describes in this comment.

The goal is that users can:

• Convert a block into a reusable block, and give it a name
• Convert a reusable block back into a regular block
• Edit a reusable block within a post and have the changes appear across all posts
• Insert an existing reusable block into a post
• Delete an existing reusable block

This is a good place to start with and iterate on as it isn't too technically difficult, it offers a lot of value to users (e.g. one could create a custom HTML block to reuse throughout their blog), and it moves us a step closer to a world where Gutenberg can handle theme customisation.

I'm splitting the overall work into roughly three PRs:

1. Adding the REST API (that's this one!)
2. Adding a core/reusable-block block to the editor that can be rendered and edited
3. Adding UI to the editor for adding, deleting, attaching and detaching reusable blocks

[youknowriad]

Thanks for working on this, this is a killer feature.

I'm adding some REST API people as reviewers for a better review.

I don't think the type and the attributes are being saved yet, are they?

[noisysocks]

Thanks @youknowriad!

I don't think the type and the attributes are being saved yet, are they?

Ah, I forgot to update this PR's description!

I decided to omit type and attributes in lieu of just having Gutenblock HTML in content. That is, a reusable block now looks like this:

{
  "id": "358b59ee-bab3-4d6f-8445-e8c6971a5605",
  "name": "My cool block",
  "content": "<!-- wp:core/paragraph -->\n<p>Hello <strong>World</strong>! How are you?</p>\n<!-- /wp:core/paragraph -->"
}

This simplifies the client code that works with the API (here and here), since we can just use Gutenberg's parse and serialize functions.

[youknowriad]

@noisysocks Oh great! in that case, this is looking good to me. Might be better to get a REST folk Review and merge.

[westonruter]

@noisysocks I think it should include the block in the type. Why omit it? Also, I think the block attributes should be made available in parsed form as readonly. We have the parsing logic in PHP so we should use it. Eventually, if we have PHP implementations of the various attribute sources, then they could be included among attributes as well.

[youknowriad]

I think it should include the block in the type. Why omit it? Also, I think the block attributes should be made available in parsed form as readonly.

I personally don't like "duplication" because it means, something could go out of sync easily, and it seems weird to me to store the serialization and a half parsed block in the same structure. I see two options:

• Keep it as is, store the HTML raw content
• or Store attributes + block type instead of the raw content.

Unless we have the PHP implementations of the attributes matchers #2751 the first option is the achievable one.

[westonruter]

@youknowriad That's why I suggest that the type and attributes properties should both be readonly. So it could not go out of sync.

The type is normally readonly in the REST API anyway: https://github.com/WordPress/wordpress-develop/blob/e8e027e7a6c028c0d72cd005ac8426b046583880/src/wp-includes/rest-api/endpoints/class-wp-rest-posts-controller.php#L1766-L1771

[noisysocks]

@westonruter The frontend code I wrote didn't use those properties, so I figured we ain't gonna need it. Happy to add them back in as readonly fields. Is there a use case for them that you foresee? Third party API consumers is all that comes to my new-to-Gutenberg mind.

[rmccue]

The type is normally readonly in the REST API anyway

Post types are immutable because each type has their own specific handling, and changing it would require two controllers working together to handle that. I'm not sure if that's something that needs to be considered for Gutenberg blocks?

[westonruter]

It just seemed that having a type would make the REST block resources more closely aligned with the other REST resource schemas. True we can add it later, as also adding parsed attributes.

[youknowriad]

Let's get this merged to move forward with the other PR. I'm fine revisiting the API once we get the server side attribute parsing.

Nice work