feat(api) expose arbitrary plugin data from a schema-meta.lua #5171
Conversation
kong/api/routes/plugins.lua
Outdated
| @@ -186,6 +186,24 @@ return { | |||
| end | |||
| }, | |||
|
|
|||
| ["/plugins/meta/:name"] = { | |||
There was a problem hiding this comment.
/plugins/schema/:name has been deprecated and moved over to /schemas/plugins/:name (/plugins/X/* is generally used by plugin X so adding entries there is prone to naming conflicts).
In the case of /plugins/schema/:name, it has been deprecated and moved over to /schemas/plugins/:name.
Perhaps we could do the same and do /schemas/plugins/:name/metadata? The /schemas/* entries are currently defined in kong/api/routes/kong.lua.
There was a problem hiding this comment.
what about /plugins/:name/metadata ? it's really not about schema at all, after all
There was a problem hiding this comment.
I think we should move away from /plugins endpoint.
Do we plan on including meta for custom DAOs as @bungle is asking. And is it possible that we have these meta for core entities too some day?
I think these extensions could be useful in future to further add in more meta for each entity.
I think we should this under and /meta collection of endpoints as /meta/plugins/:name, which keeps the door open for core entities in future, such as /meta/service.
kong/api/routes/plugins.lua
Outdated
| end | ||
|
|
||
| -- TODO: either unload module or use loadfile() instead | ||
| local ok, meta = utils.load_module_if_exists("kong.plugins." .. name .. ".schema-meta") |
There was a problem hiding this comment.
This is a matter of taste, but I would just go with .metadata instead (schema-meta sounds too much like metaschema, which is unrelated, and even more so to the also-confusing schema_meta table from the database migrations which is even more unrelated).
There was a problem hiding this comment.
Do we plan to include metadata of DAOs too?
There was a problem hiding this comment.
As I understand the requirement, it's about user-visible info to describe the plugin itself, description, type, icon. I don't think DAOs are visible enough to need such annotations.
(Of course, once it's in place, somebody will find new uses for it)
javierguerragiraldez
force-pushed
the
feat/meta-info
branch
from
b38a855
to
3f8443f
Compare
javierguerragiraldez
force-pushed
the
feat/meta-info
branch
from
3f8443f
to
5392dc1
Compare
| description = [[ Developer-supplied data. ]], | ||
| ["/metadata/plugins/:name"] = { | ||
| GET = { | ||
| title = [[ A plugin's metadata. ]], |
There was a problem hiding this comment.
the title field usually starts with an action verb, with no period:
| title = [[ A plugin's metadata. ]], | |
| title = [[Retrieve the metadata for a plugin]], |
| @@ -390,6 +391,33 @@ return { | |||
| }, | |||
| }, | |||
| }, | |||
| metadata = { | |||
| title = [[ Metadata ]], | |||
| description = [[ Developer-supplied data. ]], | |||
There was a problem hiding this comment.
This probably needs at least a paragraph-long, explaining that this is arbitrary free-form data, etc.
There was a problem hiding this comment.
There is an implicit assumption that almost everything on the admin api is part of the compatibility promise.
If this is going to be free form data, it would help us in future if we clearly document the compatibility promise here for Open source.
There was a problem hiding this comment.
I know I asked for this feature, but I get cold feet when we save user-generated, user-visible, free-form data, especially without a plan for localization. Plugin category (Authentication, Logging, etc) and possibly icon URL seem less problematic, but this begs the question whether all of this should go in an external registry as has been suggested elsewhere.
| return kong.response.exit(400, { message = "Bad query" }) | ||
| end | ||
|
|
||
| -- TODO: either unload module or use loadfile() instead |
There was a problem hiding this comment.
load_module_if_exists wraps require and is the way used for loading plugin modules elsewhere, so it's probably best to keep using it and unload the module from package.loaded.
|
@Kong/team-interfaces is this what you need? |
|
@javierguerragiraldez sorry, this fell off our radar a bit. Will get back to you by end of this week. |
| metadata = { | ||
| title = [[ Metadata ]], | ||
| description = [[ Developer-supplied data. ]], | ||
| ["/metadata/plugins/:name"] = { |
There was a problem hiding this comment.
I was discussing this with @darrenjennings , who makes the good point that while this is RESTful and consistent with the rest of the Admin API, it also requires the frontend to make upwards of 40 API calls just to render a list of plugins like https://manager-steady.kong-cloud.com/default/plugins/select/. That's not really practical, but the alternatives don't fit well into the Admin API as it exists today.
There was a problem hiding this comment.
a few alternatives off the top of my head:
- gather the metadata of all installed plugins on a single call (just
/metadata/plugins/, without a name?) - let the client ask for specific metadata fields (
/metadata/plugins/<name>/?f[]=icon&f[]=author&f[]=description&f[]=licence. optional plugin name, as on previous point). after all, only known fields can be rendered on the UI, right? - use a registry. not only can be managed, but could be GraphQL if you wish!
personally, I still think a registry is the best solution, but i'm aware that the decision hinges mostly on what's the desired process for external plugin writers.
Summary
Adds a
/plugins/meta/:nameendpoint that returns a JSON representation of the value returned by a (optional) schema-meta.lua module in the plugin directory.Any case of wrong plugin name, missing schema-meta or bad Lua syntax results in a 404 response. If no name is given, returns a 400 response
Issues resolved
PoC for Trello card: https://trello.com/c/ut8gMx93