Opened 3 months ago
Last modified 2 months ago
#8124 new feature request
Plugin Info API need to provide schema of fields for downstreams
| Reported by: |
|
Owned by: | |
|---|---|---|---|
| Milestone: | Priority: | low | |
| Component: | API | Keywords: | |
| Cc: |
Description
A few of internal functions and tools are using the Plugin Info API (notably, https://api.wordpress.org/plugins/info/1.2/?action=query_plugins&request) to retrieve information of plugins from the official plugin repository. The API endpoint changes over time, but the downstream documentation never follow up with the changes.
For instances:
- wp-cli's wp plugin searchcommand
- WordPress's own plugin_api
Both rely on the fields provided in the API. But neither of the documentations are updated. Most notably a "url" field was in the API, but is seemingly no longer exists. While some additional fields (such as "download_link") are there undocumented.
The situation is sub-optimal.
An optimal way to document the API changes is to provided an additional JSON schema that can be mentioned in an extra field "$schema" in the API endpoint. This schema format is program-readable, which may facilitate automatic or semi-automatic generation of the proper downstream documentation(s).
It takes Claude less than 5 minutes to generate a close-to-proper schema. The main point is to properly author, keep and maintain the schema along with the API changes in the future.
{ "$schema": "http://json-schema.org/draft-07/schema#", "title": "WordPress Plugins API Response", "description": "Schema for WordPress.org plugins API response containing pagination info and plugin data", "type": "object", "required": ["info", "plugins"], "properties": { "info": { "type": "object", "description": "Pagination and metadata information", "required": ["page", "pages", "results"], "properties": { "page": { "type": "integer", "description": "Current page number", "minimum": 1 }, "pages": { "type": "integer", "description": "Total number of pages available", "minimum": 1 }, "results": { "type": "integer", "description": "Total number of results across all pages", "minimum": 0 } } }, "plugins": { "type": "array", "description": "Array of plugin objects", "items": { "type": "object", "required": [ "name", "slug", "version", "author", "author_profile", "requires", "tested", "requires_php", "requires_plugins", "rating", "ratings", "num_ratings", "support_threads", "support_threads_resolved", "active_installs", "downloaded", "last_updated", "added", "homepage", "short_description", "description", "download_link", "tags", "donate_link", "icons" ], "properties": { "name": { "type": "string", "description": "Plugin display name (may contain HTML entities)" }, "slug": { "type": "string", "description": "Plugin slug used in URLs and file paths", "pattern": "^[a-z0-9-]+$" }, "version": { "type": "string", "description": "Current plugin version", "pattern": "^[0-9]+(\\.[0-9]+)*(\\.[0-9]+)?$" }, "author": { "type": "string", "description": "Plugin author (may contain HTML links)" }, "author_profile": { "type": "string", "format": "uri", "description": "URL to author's WordPress.org profile" }, "requires": { "type": "string", "description": "Minimum required WordPress version" }, "tested": { "type": "string", "description": "Latest WordPress version tested" }, "requires_php": { "type": "string", "description": "Minimum required PHP version" }, "requires_plugins": { "type": "array", "description": "Array of required plugin dependencies", "items": { "type": "string" } }, "rating": { "type": "integer", "description": "Overall rating out of 100", "minimum": 0, "maximum": 100 }, "ratings": { "type": "object", "description": "Breakdown of ratings by star count", "required": ["5", "4", "3", "2", "1"], "properties": { "5": { "type": "integer", "description": "Number of 5-star ratings", "minimum": 0 }, "4": { "type": "integer", "description": "Number of 4-star ratings", "minimum": 0 }, "3": { "type": "integer", "description": "Number of 3-star ratings", "minimum": 0 }, "2": { "type": "integer", "description": "Number of 2-star ratings", "minimum": 0 }, "1": { "type": "integer", "description": "Number of 1-star ratings", "minimum": 0 } } }, "num_ratings": { "type": "integer", "description": "Total number of ratings", "minimum": 0 }, "support_threads": { "type": "integer", "description": "Number of active support threads", "minimum": 0 }, "support_threads_resolved": { "type": "integer", "description": "Number of resolved support threads", "minimum": 0 }, "active_installs": { "type": "integer", "description": "Number of active installations", "minimum": 0 }, "downloaded": { "type": "integer", "description": "Total number of downloads", "minimum": 0 }, "last_updated": { "type": "string", "description": "Last update timestamp in human-readable format", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2} [0-9]{1,2}:[0-9]{2}(am|pm) GMT$" }, "added": { "type": "string", "description": "Date when plugin was added to repository", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$" }, "homepage": { "type": "string", "format": "uri", "description": "Plugin homepage URL" }, "short_description": { "type": "string", "description": "Brief plugin description" }, "description": { "type": "string", "description": "Full plugin description (may contain HTML)" }, "download_link": { "type": "string", "format": "uri", "description": "Direct download URL for plugin ZIP file" }, "tags": { "type": "object", "description": "Plugin tags as key-value pairs", "patternProperties": { "^[a-z0-9-]+$": { "type": "string" } } }, "donate_link": { "type": "string", "description": "Donation link URL (can be empty string)", "anyOf": [ { "type": "string", "format": "uri" }, { "type": "string", "const": "" } ] }, "icons": { "type": "object", "description": "Plugin icon URLs", "properties": { "1x": { "type": "string", "format": "uri", "description": "Standard resolution icon URL" }, "2x": { "type": "string", "format": "uri", "description": "High resolution icon URL" }, "svg": { "type": "string", "format": "uri", "description": "SVG icon URL" } }, "additionalProperties": false } }, "additionalProperties": false } } }, "additionalProperties": false }
Change History (6)
#2
@
3 months ago
- Priority changed from normal to low
Officially, the WordPress.org API's are for consumption by WordPress itself only, and 3rd-party clients are supported in a best-effort manner.
What benefit would a schema provide to them? Other than documenting the properties contents? As the output of the API may change (in a backwards-compatible manner) at any time with an update to the schema.
Most notably a "url" field was in the API, but is seemingly no longer exists.
A 'url' field has never been present as far as I know.
I suspect this is a copy-paste error in the documentation from another API.
The underlying data endpoint for the plugin endpoint is here:
https://github.com/WordPress/wordpress.org/blob/trunk/wordpress.org/public_html/wp-content/plugins/plugin-directory/api/routes/class-plugin.php
#3
@
2 months ago
I can only say that the WordPress ecosystem as a whole can enjoy a much more robust development experience if upstream pass on more meta information of their platform.
For instance, wp-cli has been the go-to DevOps tool for developers for years. Even the official WordPress Playground (as currently used by official Plugin Directory for Live Preview) has to have it supported as external library. An accurate description of the API provides an accurate documentation to tools, and in turn provides a better experience for developers and users.
The effort is minimal, I'd say. WordPress source code can refer to it internally for relevant documentations in the future. It is a positive addition to both WordPress internal and to the ecosystem with a very low cost.
#5
follow-up:
↓ 6
@
2 months ago
@dd32: I've read the source code from the file you pointed to.
This seems to be responsible to provide information of individual plugin. But is there an openly available source code file for the actual API endpoint? If I were to add a schema anywhere, it need to resides in the API server somewhere.
#6
in reply to:
↑ 5
@
2 months ago
Replying to yookoala:
This seems to be responsible to provide information of individual plugin. But is there an openly available source code file for the actual API endpoint? If I were to add a schema anywhere, it need to resides in the API server somewhere.
That's the endpoint used to generate the data for the other endpoints, you'll find the actual API server in the standalone folder, ie. this: https://github.com/WordPress/wordpress.org/tree/trunk/wordpress.org/public_html/wp-content/plugins/plugin-directory/standalone and an example (not used on WordPress.org) implementation here: https://github.com/WordPress/wordpress.org/blob/trunk/wordpress.org/public_html/wp-content/plugins/plugin-directory/standalone/plugins-info-api.php
The schema therefor would likely be generated by WordPress itself in the wp-json endpoints, and the correct way to supply a patch would be to document that rest-api endpoint mentioned previously.
Should this be accepted, the API may change to something like this:
While I would love to help, this part of code don't seem to be available in your public subversion server (or GitHub).
Please let me know if, and how, I might help. Thanks.