Revolyssup commented on issue #9577:
URL: https://github.com/apache/apisix/issues/9577#issuecomment-1581984384
Proposed design for GET endpoint:
/apisix/admin/plugins/{name}
Query params:
- subsystem: Only this subsystem will be searched for {name} when name is
provided. The default value of subsystem when not provided in query parameter
is to search in all subsystems. Possible values are : http, stream. This is so
that by default when subsystem is unspecified, you search through all
subsystems to remove ambiguity and to search across a given subsystem - you
pass it in query param
---
**Removing redundant all=true**
this query params adds confusion and is usually not found in REST APIs.
The default behaviour of any RESTful endpoint is to return all results for a
given resource unless specified to filter via a query parameter. So here I
propose to get rid of `all` to stick to convention.
/apisix/admin/plugins is equivalent to name not being passed. and When
{name} is not provided then by default all plugins for the given
subsystem(default: all subsystems) will be listed.
**Backwards compatibility:**
Currently the output of:
`/apisix/admin/plugins` is `{"error_msg":"not found plugin name"}` so no one
would be using it.
Instead currently to get all plugins, the endpoint used is:
`/apisix/admin/plugins?all=true`. With the proposed design all=true will simply
be ignored and there would be no breaking change.
By default, if subsystem is not specified, the response defaults to
returning L7 plugins. This is a breaking change since the proposal is to return
all plugins when the subsystem is unspecified to remove ambiguity. So if
somewhere this API is used in a way where it assume to only get L7 plugins,
after this change they will have to add subsystem=http to make things explicit.
Currently when name is specified like
http://127.0.0.1:9180/apisix/admin/plugins/http-logger?subsystem=stream, the
subsystem field is ignored all together. The proposed design is to have uniform
behaviour. Currently the above specified path returns http-logger even when
there is no such plugin in stream subsystem. After the proposed changes, the
search will be strict and the above endpoint will return no results.
---
**Proposal Summary**
Search via name requires the name to be passed in URI and filter by
subsystem requires the subsystem to be specified in query params. These two are
orthogonal search vectors.
- `/apisix/admin/plugins/{name}` = Find `{name}` plugin across all
subsystems
- `/apisix/admin/plugins/{name}?subsystem={xyz}` = Find `{name}` plugin in
`{xyz}` subsystems
- `/apisix/admin/plugins` = Return all plugins across all subsystems
- `/apisix/admin/plugins?subsystem={xyz}` = Return all plugins across
`{xyz}` subsystem
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
