WordPress.org_API Errata

[TonyGravagno]

Ref https://codex.wordpress.org/WordPress.org_API
(I'll edit this when doc is moved to DevHub Common APIs)

I'm starting an errata thread here. Individual issues can get pulled out to new tickets as desired.

1. Dead link to orbisius.com/blog
2. The Browse Happy end-point is undocumented on the API page, and appears to be unresponsive, though it is probably logging data transparently.
3. The Serve Happy end-point is undocumented on the API page, and as-is returns an error.
4. The Envato/tutsplus third-party examples by @hchouhan for API v1.0 are helpful, but that page is over 10 years old, outdated, and subject to disappear. I suggest the wisdom should be located in, or closer to the official API page, in case it disappears like other third-party resources.
5. The blog by @dd32 linked from the doc, is very helpful. But as above, I believe the wisdom (now 13 years old) should be incorporated into the doc page, just in case Dion / @dd32 decides to archive his content. That is, I see old docs, and docs hosted off-site, as vulnerabilities, only in that we lose the information if it's not hosted in the official repo.
6. Now that the v1.0 version is more of a historical artifact, perhaps this page could be updated with current info only, with the v1.0 info archived somewhere? I have no doubt that some code is still out there somewhere that uses v1.0, and the end-points are still active. But as with everything else in our world, like 16bit exe files, old versions of WP, and deprecated dependencies, perhaps it's time to nudge things forward.
7. It's understood that the Plugin Directory API is similar to the Theme Directory API, but there is no text about this, no on-page example, and no reference to the code. Perhaps the doc could be updated to make this more of a first-class citizen, even in this, "not suitable for public consumption" material.
8. Functionally (almost certainly a code issue and not docs, but just checking...), it seems the plugin API ignores 'field' specs and returns all fields regardless of true/false client directives. If the doc is inaccurate in how it describes how to use field specs then let's get a good example in the doc.
9. There are no fields documented for plugins.
10. Ref https://core.trac.wordpress.org/ticket/51126 for (?) related material that might need to be added here.
11. Add link to Events API source and here and improve related info.
12. Adding a link to the Developer plugins_api function and themes_api might help to move people toward official tooling so that they are less inclined to use the core API.
13. Add details for http://api.wordpress.org/core/stable-check/{version}/
14. Good info by Dion about why versions of WordPress might or might not be marked as "insecure".
15. Add details for http://api.wordpress.org/core/version-check/1.7/?version={version}&channel={channel} (As an example of "need", changes were made to the API this year and there's no documentation about it.) v1.6 returns PHP serialized result. v1.7 (Python) returns JSON-encoded results. There is no info about the "channel" attribute, which is important for this endpoint.
16. Add https://profiles.wordpress.org/wp-json and related wp-json end-points (which might deserve their own page?).
17. Add https://wordpress.org/support/plugin/{name}/reviews/feed and related end-point details.
18. Add https://api.wordpress.org/stats/plugin/1.0/?slug={name} Stats end-point (stats/mysql, etc)
19. Add example for Themes endpoint: https://api.wordpress.org/themes/info/1.2/?action=theme_information&request%5Bslug%5D={theme_slug}
20. Need to see if Reason for Plugin Closed is available via API, and which attribute has this data. Might lead to new request for attribute in the API. Ref this ticket on the topic and others that are linked from there.
21. Add a note about how "fresh" the data is after changes. For example, an author updates their plugin - how soon afterward is that data exposed via the API? This can change expectations of those who consume the data and reduce the number of requests.
22. It's kinda crazy, but api.wordpress.org occasionally gets reported to IP abuse sites. The site has been whitelisted with intervention from wordpress.org staff, but it still gets reported by various entities and it's possible that the site may not be accessible to those who are making outbound queries to the site. Given this awkward yet real phenomenon, I think a helpful note on the doc page is warranted.
23. It should also be noted that wordpress.org may block inbound IP addresses that are abusing services : Rather than simply blocking inbound connections, the API "almost always" returns an HTTP error result. (Ref Dion in forum and in Slack)

Over the years, public questions about this API have received an appropriate response that it is mostly for internal / core use and outside use is discouraged. Much of the source is actually closed-source even though some of it is published. It's also been noted that stats are aggressively deleted after aggregation. Dion recently called this "unofficial documentation" (or maybe he was referring to his own link). Perhaps the official position about this API can be stated here clearly, with FAQs answered to eliminate some future hunt-n-peck by those seeking information about ecosystem resources (events, plugins, themes, credits, ...).

My overall goal here is to see this page made clear for those on the meta team who need to use it, and appropriately clear about what the lines are for others. There actually are resources as noted above which can be used by non-meta developers, and rather than simply discouraging use of the meta API, perhaps this doc page can encourage use of other resources which are, maybe not "intended for" others but at least more appropriate for others.

I'm also putting this up here so that we can get one place where, if the official answer is "no, we do Not want to document that resource", that can be stated here. (Not so much as "we are not telling people that the money is in the freezer". 😁 ) And again, if the info will not be in this public doc, then for the meta team, where is the detail expected to be for authorized team members?

Pertinent notes by @Otto42 that attempt to balance this note about adding more info:

Things like stats are a very guarded thing because of privacy reasons. Basically, we have a lot of information that we intentionally do not give out. We try very hard not to give it out. In fact, we try very hard to delete it.
The more detailed we break it down, the more possibilities for authors to use that breakdown to further violate user privacy.

Here's another Slack post by Otto:

For there to be API documentation, their first need to be a plan for the API and a method of long-term support around providing that documentation stayed up to date.
Currently no such plan exists, as the API is meant only really for WordPress core and WordPress.org to use. We don't mind other people using it, but any non-official uses of it are not supported and could change at any time.
So documentation for it is unlikely, because there isn't any official method of support for it yet, and no real plan to have such. Any such things are low priority.

Another ticket quoting Otto.

This is an equally relevant recent note by @iandunn :

it's stable and very high priority to keep running. Support for community purposes is mostly a "if we have time" kind of thing, but anyone is welcome to use it (assuming all the it's in good faith, reasonable usage limits, etc)

The messaging about the API is not mixed but it is not absolutely clear either. I'll take a shot at providing some brief text for this if it would help. Or, to quote Otto "So documentation for it is unlikely" ... if this page is NOT going to get any updates, perhaps that should be made very clear as well for both the authorized meta team and others.

[github-actions]

Heads up @WordPress/docs-issues-coordinators, we have a new issue open. Time to use 'em labels.