Review API endpoints

[tellyworth]

Copied from https://meta.trac.wordpress.org/ticket/1579#comment:13 -

We need

• A stand alone PHP script which reads the WordPress postmeta table to perform updates
• (ideally) A stand alone PHP script which can handle the plugin_information requests & /hello-dolly.json requests. I'd probably suggest we should just cache a full response from the REST API (/wp-json/plugins/v1/plugin/hello-dolly/) and handle the fields and conditional wp_version checks, as well as the output format (PHP serialized, XML, and JSON) in that handler
• A REST API Endpoint which can be used for the hot_tags endpoint
• A REST API Endpoint which can be used for the query_plugins endpoints, this mostly wraps WP_Query but has a lot of random and weird logic burried in it

Loading WordPress for all these requests isn't going to be viable, but for some we'll have little choice.

• The update handler should most definitely not load WordPress at all.
• The hot_tags handler could just cache the result of the WordPress endpoint, so it doesn't require * loading WordPress often.
• The plugin_information handler would be a good one to cache, and not hit WordPress on, as it's requested often enough and accounts for a significant amount of the api traffic.
• The plugin_information handler via hello-dolly.json should be made cacheable, that means it should only use the data contained within the URL for the response, fetching the WordPress version from the user_agent isn't viable

Task - review above, and create tickets for anything missing or broken. Those tickets probably belong in Milestone 8.

[dd32]

Just noting it here - The FAQ changes resulted in <dl> and <dt> in the FAQ section, these are not allowed tags in the WordPress interface.
We'll need to 'unwrap' these in the API from a <dl> to some form of a <h3>Q</h3>A format.

[tellyworth]

In 4458:

Plugin directory: fix some minor regressions in API output.

See #2112

[dd32]

In 4559:

Plugin Directory: Allow us to return the FAQ section with <h4> instead of <dl> for existing WordPress versions.
Also fixes the hot_tags endpoint to work correctly.

See #2112.

[dd32]

In 4560:

Plugin Directory: Expose Screenshots in the sections section of the API response so WordPress can display them.

See #2112

[dd32]

In 4567:

Plugin Directory: When running on WordPress.org infrastructure, include wp_json_encode() from our API includes in the event that WordPress wasn't loaded on this request.
This fixes cases where API results were incorrectly encoded due to UTF8 issues, which ultimately caused json_encode() to fail.

See #2112

[dd32]

In 4572:

Plugin Directory: API: Return an empty array of tags for when the hot_tags api is unavailable.
The handling for the 'error' key was previously being matched by.. the error tag.. Even when an error is returned to the client though, WordPress includes no error-case handler here, so returning an empty array is safer.

See #2112

[obenland]

@dd32 Re: [4559]: Could we try using div elements instead of p to group FAQ answers? I assume we run them through autop() somewhere in the process chain and we end up with p as children of p, which is not allowed and leads to weird display behavior.

Do we only use that new FAQ markup in the API?

Could we use DATE_ATOM instead of custom date formats for all date-related information in the API?

I'd love for us to return raw plugin review data instead (or in addition to) the marked up version we currently send out. In its current form it's harder than it has to be to individualize display, things like the amount of reviews for example

[dd32]

Could we try using div elements instead of p to group FAQ answers?

Sure, I didn't notice it was nesting <p> elements. <div> makes sense in that case. edit: If it's actually being display filtered somewhere, we could also just skip adding any wrapping elements.

Do we only use that new FAQ markup in the API?

Yes, That FAQ markup is for the API only, it's an "old style" markup which matches what we previously returned, as core has specific styling for that exact markup (See [4310]).

I fully expect to add an extra field to indicate that the client wants the semantic markup and handle it nicely within WordPress too, down the line, leaving this just as BC stuff.

Could we use DATE_ATOM instead of custom date formats for all date-related information in the API?

AFAIK, no, the formats used are as clients expect it. But if you can point to the field you're referencing, and why, I might be able to suggest more details.

I'd love for us to return raw plugin review data instead

That's possible, and will eventually be added I'm sure when someone rebuilds the wp-admin component, it'll just be hidden behind a feature-flag (by setting review_data field to true or something). I'd highly suggest against doing anything of the sort in the short term though, as the whole review styling needs a rethink, what data to show, replies, etc, and it's far easier to design the raw format with that in mind.

[obenland]

Replying to dd32:

If [FAQs are] actually being display filtered somewhere, we could also just skip adding any wrapping elements.

True. Here too we could just return the raw data and let apps decide on how they'll display it for themselves.

I fully expect to add an extra field to indicate that the client wants the semantic markup and handle it nicely within WordPress too, down the line, leaving this just as BC stuff.

I wonder if we should designate the /plugins/v1 endpoints for core and the /wp/v2 endpoints (with raw data) for apps?

Could we use DATE_ATOM instead of custom date formats for all date-related information in the API?

[If] you can point to the field you're referencing, and why, I might be able to suggest more details.

Specifically the last_updated field. I tried dumping it into moment.js but it complained about the non-ISO format. I was able to mitigate it by passing a parsing format, but standardizing it on ISO 6801 could make sense for more than just that.

[dd32]

I wonder if we should designate the /plugins/v1 endpoints for core and the /wp/v2 endpoints (with raw data) for apps?

The /plugins/v1/plugin/ endpoint is specifically designed for consumption by api.wordpress.org only, and I'm probably going to lock it down to exactly that now. The endpoints there are too heavy for regular usage and should not be used by any clients directly (including the react stuff).

So flesh out /wp/v2/plugins instead IMHO.

[obenland]

Perfect!

[dd32]

In 4727:

Plugin Directory: Add a custom table containing a subset of plugin meta used for api.wordpress.org/plugins/update-check/.

See #2112

[dd32]

In 4764:

Plugin Directory: Use translated data for the api.wordpress.org info endpoint.

• Also translates screenshot titles on the front end
• Also uses plugin tags in API info endpoint rather than defunct categories.

See #2112
Fixes #2415

[dd32]

In 5236:

Plugin Directory: Update API: Fix a bug in the update api updater which would cause new plugins not to get a row added to the version lookup table for the update api.
This also removes the ability for a plugin in approved state from being inserted, just to limit the size of the table from the thousands of approved-but-not-uploaded plugins.

See #2112