Download stats API returning unexpected results

[pyves]

Transferred from ​#WP54989.

The download stats API endpoint documented [here](​https://codex.wordpress.org/WordPress.org_API) is returning unexpected results.

Consider the following API requests:
​https://api.wordpress.org/stats/plugin/1.0/downloads.php?slug=definitely-not-a-real-plugin
​https://api.wordpress.org/stats/plugin/1.0/downloads.php?slug=100
​https://api.wordpress.org/stats/plugin/1.0/downloads.php?slug=sadikovtdjoiybvjtdoivgrdjashc

As you'll probably have guessed, none of the above plugins exist, yet the API is indicating up to several hundred daily downloads. This makes me wonder whether the API can be trusted at all, even for valid plugin slugs.

[dd32]

This specific API endpoint does return 100% invalid data for invalid requests, but returns 100% valid data for valid requests. This is by design due to spam and DDOSs against the APIs.

Simply: Don't use it for something it's not designed for, as all WordPress.org API endpoints are only intended on being used by WordPress or WordPress.org, they're not intended on being "public data API's", and may change their output format to suit requirements at any time.

[dd32]

@pyves Please use this API instead: https://api.wordpress.org/plugins/info/1.0/akismet.json instead. The .downloads field there is the one you want, and the API will return an error for an invalid slug.

That API is more standard and more acceptable to be used by others, while the stats endpoints are specifically WordPress.org-focused.

(Oh, you want per-day / per-month data, yeah that's not available. Deal with the 'invalid' data if they provide invalid input)

[pyves]

Replying to dd32:

Don't use it for something it's not designed for, as all WordPress.org API endpoints are only intended on being used by WordPress or WordPress.org, they're not intended on being "public data API's", and may change their output format to suit requirements at any time.

This answer is quite unexpected. I've got a few follow up questions:

• ​https://codex.wordpress.org/WordPress.org_API is publicly accessible, there is no warning that is shouldn't be used, nor any explanation on what its intended purpose is. Why is that?
• after a quick search through the support forum, I'm apparently not the first one to have stumbled upon this "public API" problem (e.g. ​https://wordpress.org/support/topic/using-the-wordpress-org-api/). Already at the time a suggestion was made to add a warning to the very same documentation, yet one of your colleagues refused to do so. Why is the WordPress.org team so keen on repeatedly misleading users?
• you suggest using ​https://api.wordpress.org/plugins/info/1.0 instead of ​https://api.wordpress.org/stats/plugin/1.0/downloads deeming it "more standard and more acceptable to be used by others". Where is this documented? It seems arbitrary given that both endpoints are documented in the same place with nothing differentiating from a external user's perspective.
• why is the API seemingly versioned (/1.0, /1.1, /1.2)? The very idea behind API versioning is to prevent output formats from changing unexpectedly, yet you're stating the opposite.

Replying to dd32:

Deal with the 'invalid' data if they provide invalid input

How am I meant to deal with invalid data if there's no way to tell it's invalid? As noted by your colleague in ​https://core.trac.wordpress.org/ticket/54989, it's intentionally been faked, so there's no way to tell whether the returned numbers are real or not.

[dd32]

The codex (​https://codex.wordpress.org/WordPress.org_API) is a public wiki, anyone can add documentation there if they wish, it's not 'official documentation', although I've edited incorrect data out of it before. The Codex is deprecated and pending shutdown, that page hasn't been migrated to any "officially maintained" locations for a reason.

The plugin-info endpoint (​https://api.wordpress.org/plugins/info/1.0) is versioned as the input/output format has changed over time, and is used by a large number of clients, it's anticipated that it will remain used and so there's no issues relying upon it, it's versioned because the WordPress software uses those endpoints and older verisons of WordPress still use the older versions of those APIs. It's not intended to be used outside of WordPress.org/WordPress but we don't prevent it. You could make a request against it to verify if a slug is valid first.

The stats endpoints are not designed for "public consumption", rather for WordPress.org-only uses. We don't prevent others from accessing the endpoints, but we don't support it. As noted it returns invalid data for invalid input due to design, due to abuse of the API. There's versioning included, but mostly to keep it inline with other API's on w.org, it'll change if the graphs that use it need to change (which has happened numerous times in the past).

[pyves]

Okay, thanks for clarifying. If the documentation is going to be removed when Codex shuts down, that should at least prevent other users from hitting these kind of issues in the future.

Back to the initial problem, am I correct in understanding that there is no supported API that returns a daily plugin download count, and that the only alternative is to combine two calls, one to the "semi-supported" info endpoint for slug validation, and one to the unsupported stats endpoint?

If so, is it worth me opening a feature request for such as API, or are there no plans of providing one in the foreseeable future?

[Otto42]

Correct, there is no official endpoint for providing this data. We use it for the graphs shown on plugin pages. That is the only extent to which it is supported. If those graphs are removed (and that is not unlikely), then the endpoint will also be removed.

[pyves]

Replying to pyves:

If so, is it worth me opening a feature request for such as API, or are there no plans of providing one in the foreseeable future?

[dd32]

We have no plans to add further APIs or importance upon metrics that offer no user value. That includes download counts.

Pleas note: There's no need to re-open the ticket, as we can see the responses, and as it's only going to be re-closed, it's just extra noise.

[pyves]

Replying to dd32:

We have no plans to add further APIs or importance upon metrics that offer no user value. That includes download counts.

Wordpress users create plugins and themes for WordPress, and then turn to Shields.io to proudly surface various pieces of information about what they've built. Whether you like it or not, our Wordpress badges are widely used, and saying there is no user value to such metrics is simply untrue. Fostering quality tooling and rich ecosystems around a product is key to its user success.

Pleas note: There's no need to re-open the ticket, as we can see the responses, and as it's only going to be re-closed, it's just extra noise.

It's customary for a user-facing issue tracking system to provide helpful and polite support. Slamming the door by repeatedly closing a ticket and ignoring half the questions is quite far off. No need to blame others for "noise", given that it is nothing but a consequence of your actions.