Pattern Directory: Create endpoints to proxy api.w.org/patterns.

[iandunn]

Fixes #26577

Description

This adds API endpoints to browse and search for patterns. Similar to the Block Directory, the endpoints in Gutenberg proxy the api.wordpress.org endpoints, to prevent w.org from receiving the user's IP address.

• http://{{ hostname }}/wp-json/wp/v2/pattern-directory/
• http://{{ hostname }}/wp-json/wp/v2/pattern-directory/?category=2
• http://{{ hostname }}/wp-json/wp/v2/pattern-directory/search?term=image

How has this been tested?

• Manual testing with Insomnia
• PHPUnit tests

Types of changes

New feature

Checklist:

• My code is tested.
• My code follows the WordPress code style.
• My code follows the accessibility standards.
• My code has proper inline documentation.
• I've included developer documentation if appropriate.
• I've updated all React Native files affected by any refactorings/renamings in this PR.

[iandunn]

@TimothyBJacobs , heads up about this, in case you have any early feedback or thoughts.

[iandunn]

The phpunit-watcher stuff is just cherry-picked from #27058, for convenience. I'll remove it before publishing the PR.

[TimothyBJacobs]

What's the difference between get_patterns and query_patterns? Will the response format be different based on that? Ideally, it wouldn't. The search endpoint should have a uniform schema.

[iandunn]

The "get" endpoint is for browsing, like https://api.wordpress.org/patterns/1.0/?action=get_patterns or https://api.wordpress.org/patterns/1.0/?action=get_patterns&category=2.

The response format is different; the get_patterns endpoint on api.w.org are proxying a CPT's default endpoint, while query_patterns is proxying Core's search endpoint. There's also some workarounds due to https://core.trac.wordpress.org/ticket/49985 and https://core.trac.wordpress.org/ticket/49538.

The api.w.org code is at https://meta.trac.wordpress.org/browser/sites/trunk/api.wordpress.org/public_html/patterns/1.0/index.php?rev=10414

I imagined that prepare_item_for_response() would normalize the responses, though, so that searching and browsing would have the same schema.

[TimothyBJacobs]

Ah, gotcha.

I imagined that prepare_item_for_response() would normalize the responses, though, so that searching and browsing would have the same schema.

That'd be great!

[iandunn]

The e2e test failure looks unrelated.

[iandunn]

Should this go behind a feature flag or experimental namespace until the other parts of the pattern directory are implemented?

[TimothyBJacobs]

Should this go behind a feature flag or experimental namespace until the other parts of the pattern directory are implemented?

From a REST API perspective, I think it should have an experimental namespace. Whether it also needs to be behind a feature flag, I'm not sure. Maybe @youknowriad has thoughts about which features warrant that behavior.

[TimothyBJacobs]

Some minor bits of feedback.

[TimothyBJacobs]

Is there a bit more context of how the patterns structure is setup on .org? Looking just at https://meta.trac.wordpress.org/browser/sites/trunk/api.wordpress.org/public_html/patterns/1.0/index.php, I'm not sure why those need to be two different endpoints if the search endpoint is only looking in the wporg-pattern subtype. The purpose of the search controller is to allow for querying multiple/all subtypes at the same time.

[iandunn]

Thanks for the review!

I think it should have an experimental namespace

👍🏻

That, and all the line-specific comments should be addressed in a45327f9f540356ce7b5f6ce402b9694a9704fd2.

I'm not sure why those need to be two different endpoints if the search endpoint is only looking in the wporg-pattern subtype. The purpose of the search controller is to allow for querying multiple/all subtypes at the same time.

Ah, that makes sense, I'll work on simplifying that. Thanks!

[iandunn]

I updated api.w.org to no longer use wp/v2/search in https://meta.trac.wordpress.org/changeset/10572/, and
2de7231c96f8cfecfdf25150129cec03ae752d5a updates this PR in light of that.

[TimothyBJacobs]

Do we still need two separate endpoints in Gutenberg at this point?

[TimothyBJacobs]

f68389b consolodates the /search endpoint into /

face663 and 9078eb7 are related. I think this is more appropriate than using term, but am curious what you think @TimothyBJacobs

This seems good to me.

[iandunn]

those locally-registered patterns should also be returned by the API.

Ah, 👍🏻

The schemas will need to match.

Local patterns have Title, content, description, viewportWidth, categories, keywords, so we should probably add keywords to the w.org API. None of the Core patterns use it, but I'm assuming it's still desired.

Locally, categories is an array of slugs, rather than IDs, so we should probably return that instead. Although, local pattern would call register_block_pattern_category(), which asks for a label in addition to the slug. Maybe we don't need to handle that here, though, since that'd be handled by whatever code eventually "installs" the w.org pattern locally? That might depend on whether or not we have that "install" flow; IIRC that's not finalized (cc @kellychoffman, @DaisyOlsen)?

[ryelle]

There really isn't a local install flow, the block code is just inserted when you click the pattern. (there has been some discussion about saving/favoriting patterns on wp.org, but we don't have that wp.org user connection on local WP sites, so the idea's been pushed off to later iterations)

You make a good point about categories though, we'll need some way of getting the categories list off wp.org + the local site to populate the category dropdown here:

On the wp.org side I've been assuming that's a static list of categories, but I don't think we want to make that assumption in the editor - that way we can add categories to wp.org without having to change Gutenberg.

[iandunn]

we'll need some way of getting the categories list off wp.org + the local site to populate the category dropdown

👍🏻 , I think that'd be best scoped to a separate PR. I opened #28204 to track it.

[TimothyBJacobs]

In light of that, I think we might want to go back to pattern-directory/search and have a pattern-directory/categories endpoint that would return the list of categories.

[iandunn]

we might want to go back to pattern-directory/search

Do you mean renaming the current / to /search, or splitting them back into / for browsing and /search for searching?

[TimothyBJacobs]

Renaming the current / to /search, or another name, but so we have "room" for a /categories endpoint.

[iandunn]

👍🏻 , I'll do that, and normalize the local/remote schemas.

I don't think we should combine the local/remote patterns in this PR, though, since it opens a can of worms. I added #28248 for that. I think we should merge this once any final requests are done, and do the rest in separate PRs.

[iandunn]

That latest batch of commits depends on some updates to w.org/patterns and api.w.org that I haven't finished & deployed yet. the test fixtures are updates to reflect the upcoming changes, though.

i'll leave a note when the w.org endpoints are updated.

[iandunn]

@TimothyBJacobs , is 5b92da59f52e91b847c2ea1312061472ea27855d the right way to do validation for the response? I dug through the docs, examples, etc, but just confused myself, and couldn't get sanitize_callback working. Is that only for the request?

[TimothyBJacobs]

Yeah, all the built in validation/sanitization handling is for request data. We don't apply that level of sanitization in the block directory, but 🤷.

[iandunn]

🤔 , it seems like a "better safe than sorry" situation to me. I wouldn't want Core to trust input any other remote APIs.

[iandunn]

@TimothyBJacobs, Do you feel like this is ready to merge from an API perspective?

@youknowriad, would you like this behind a feature flag?

[TimothyBJacobs]

Left some small bits of feedback.

[youknowriad]

@youknowriad, would you like this behind a feature flag?

Since this is a PHP change that is only backported explicitly into Core. I don't think it should necessarily be behind a feature flag. We can include in Core when we think it's ready or when it's being used by the frontend.

[iandunn]

Thanks, that sounds good 👍🏻

[TimothyBJacobs]

Looks great to me!

[iandunn]

👍🏻 thanks for the review!

I squashed all the WIP commits down, and rebased against master. Is there anything else needed to merge?

[TimothyBJacobs]

Looks great, merged.

[iandunn]

Thanks!

[mtias]

Awesome to see this progress :)