Rest API: add /revisions endpoint for global styles

[ramonjd]

Parent issue:

• Editor: expose revisions in the UI for all available post types #49601

What?

Adds an endpoint that returns revisions for the global styles custom post.

/wp/v2/global-styles/revisions

Plucked from the experimental branch:

• 🚧 Experimental: Global styles revisions #49912

Why?

In order to display revisions for global styles in the UI. See explorations in #49601 and #46667 for context.

How?

Registering a new /revisions endpoint in the Gutenberg_REST_Global_Styles_Revisions_Controller class.
Much inspiration is taken from WP_REST_Revisions_Controller.

Response example:

[
    {
        "author": 1,
        "date": "2023-04-23T23:29:24",
        "date_gmt": "2023-04-23T23:29:24",
        "id": 6,
        "modified": "2023-04-24T05:15:03",
        "modified_gmt": "2023-04-24T05:15:03",
        "parent": 4,
        "slug": "wp-global-styles-twentytwentythree",
        "settings": {},
        "styles": {
            "color": {
                "background": "var:preset|color|vivid-purple"
            }
        },
        "date_display": "5 hours ago (24 Apr @ 00:58)",
        "author_display_name": "admin",
        "author_avatar_url": "http://2.gravatar.com/avatar/ea8b076b398ee48b71cfaecf898c582b?s=24&d=mm&r=g"
    }
]

Explanations

Why not extend WP_REST_Revisions_Controller?

I did try this, but WP_REST_Revisions_Controller has a lot of custom methods and the response is geared towards revisions from posts/pages/templates that have rendered HTML content.

Also I wanted to reduce the schema and ensure maximum flexibility for global styles, which are its own class of citizen.

Testing Instructions

Run the tests!!!

npm run test:unit:php -- --filter Gutenberg_REST_Global_Styles_Revisions_Controller_Test

To test the endpoint in the site editor, fire up this branch and head over to the site editor.

In your browser's console, switch to the network tab and run the following :

await wp.apiFetch( { url: `/index.php?rest_route=%2Fwp%2Fv2%2Fglobal-styles%2F${ wp.data.select('core').__experimentalGetCurrentGlobalStylesId() }%2Frevisions&_locale=user` } );

Check the network request and response.

[ramonjd]

I did start with extending WP_REST_Revisions_Controller, but global style revisions need special treatment, e.g.,

• JSON instead of rendered HTML
• We only need one route right now (to fetch some revisions for the UI)
• I wanted to add some custom properties/schema

The methods I had to overwrite contained just as much code as doing it from scratch.

Happy to go back to extending WP_REST_Revisions_Controller if folks think it's better longer term.

[ramonjd]

Thanks for all the nudges @spacedmonkey 🙇

[ramonjd]

We don't need half of these properties, at least for the purposes of planned UI changes: #49601

I just added them because they were in the revisions controller.

I've a mind to remove them.

[andrewserong]

Which ones were you thinking of removing?

In principle, I quite like the idea of trying to keep a close parallel between the two revisions endpoints so that there's predictability between the endpoints if someone were to write a plugin or other tool that wants to call the endpoints — but I have only just started looking at this PR 😄

[ramonjd]

Good question. I was wondering whether to include only a minimal set of properties that will serve to create the revisions UI (see #49601), and leave it open for extension later, but you're right about predictability. There's no harm in leaving them in. 👍

[ramonjd]

Which ones were you thinking of removing?

I've already left out slug, but was thinking of removing dates (except for the display one).

Do you reckon I should reinstate slug? I guess it could be at least used as a key for iterable components

Here's a raw preview of all standard, post revision props (ignore the rendered content)

[andrewserong]

I've already left out slug, but was thinking of removing dates (except for the display one).

Personally, I'd keep all the dates ones so that they're filterable / sortable by the consumer.

I've already left out slug, but was thinking of removing dates (except for the display one).

We've already got id, so slug might not be all that useful, especially since title isn't present in the response, and users aren't able to update the title of the global styles entry, anyway?

I quite like the balance that you've already got in this PR, it's looking quite good to me 🙂

[github-actions]

Flaky tests detected in 041c382.
Some tests passed with failed attempts. The failures may not be related to this commit but are still reported for visibility. See the documentation for more information.

🔍 Workflow run URL: https://github.com/WordPress/gutenberg/actions/runs/4804073257
📝 Reported issues:

• [Flaky Test] should filter results properly #44462 in specs/site-editor/global-styles-sidebar.test.js

[andrewserong]

Nice work honing in on an MVP for this endpoint @ramonjd! It's all testing nicely for me:

✅ Responses return the expected data
✅ Tests pass and appear to have an appropriate level of coverage
✅ Accessing the endpoint directly correctly fails as a non-logged in user (401)
✅ Accessing the endpoint while logged in as a non-admin user (e.g. Author) correctly 403s
✅ Link to the new endpoint is correctly added to the existing global styles endpoint
✅ Schema returned looks correct, based on an OPTIONS request:

await wp.apiFetch( { method: 'OPTIONS', url: `/index.php?rest_route=%2Fwp%2Fv2%2Fglobal-styles%2F${ wp.data.select('core').__experimentalGetCurrentGlobalStylesId() }%2Frevisions&_locale=user` } );

I've left a few comments, mostly just ideas or thoughts for things to add in potential follow-up PRs, and likely to be added before a core merge for 6.3 to make sure that the endpoint is well-rounded enough to feel consistent with the revisions endpoint. For now, I think this a great place to begin, with a simple collection endpoint that only returns the latest 100 revisions 👍

Also, I quite like the decision to copy / paste what was needed from the revisions endpoint rather than extending the existing class, so that it's possible to continue to experiment and add / change things in this endpoint safely within the plugin and in a single place. I imagine there'll be subsequent iterations prior to backporting to core anyway.

LGTM, nice work digging into all the details! ✨

[andrewserong]

Will there also be a route for accessing an individual revision / deleting a revision?

I imagine that's not required for the initial version of the endpoint (exposing a list of revisions in the site editor UI), but could be a good follow-up PR to ensure consistency?

[ramonjd]

I agree. I expect one day they'll both be needed. I haven't heard anything about it for 6.3.

[andrewserong]

Again, I imagine this isn't required for the initial goal for this endpoint, but would we eventually include support for common collection args (like per page, offset, order, etc so that paginated responses would be possible?)

[ramonjd]

Exactly, and, now that you've raised it, I can probably remove it from this iteration. I think it was a leftover from experimentation. Thank you!

[andrewserong]

Just following on — so to begin with, this endpoint only supports listing out the 100 most recent global styles revisions, in descending order. That sounds good to me!

[ramonjd]

It's the MVP 😄 It's possible we'll need finer query params in the future, but there are no requirements and nothing has been planned so it could be a long way off.

[andrewserong]

Is this a stray comment? It looks identical to the following line 😄

[ramonjd]

🤦

[ramonjd]

Thanks @andrewserong 🙇 I'll update with the small changes to correct the minor oversights.

As more requirements come in I hope it'll serve as a good base to extend with functionality similar to WP_REST_Revisions_Controller