Background The current implementation of fetching plugins is ambiguous and confusing. Few examples are below: If you pass random strings into the subsystem query, it still defaults to the result for http:
curl "http://127.0.0.1:9180/apisix/admin/plugins?all=true&subsystem=strm"; | jq 'length' 77 curl "http://127.0.0.1:9180/apisix/admin/plugins?all=true&subsystem=htt"; | jq 'length' 77 curl "http://127.0.0.1:9180/apisix/admin/plugins?all=true&subsystem=random"; | jq 'length' 77 While this may or may not be the intended behaviour, it is not very straightforward. There seems to be no way to get ALL plugins (L7 & L4). I expected /apisix/admin/plugins?all=true to return all plugins but instead it defaults to HTTP. In short, curl -s "http://127.0.0.1:9180/apisix/admin/plugins?all=true"; | jq 'length' 77 seems to be the same as curl -s "http://127.0.0.1:9180/apisix/admin/plugins?all=true&subsystem=http"; | jq 'length' 77 Currently exposed API for GETing these plugins goes against the REST convention. The purpose of this proposal is to simplify the API and make it more intuitive and conventional. Problem to be solved Remove unnecessary query parameters like ?all=true which, in fact, should correspond to the default behaviour of any RESTful resource and make the filtering of these plugins based on subsystem to be less ambiguous and confusing. The benefits of solving this problem The behaviour of the API becomes much more transparent and standardised. Scope of requirements Admin API design /apisix/admin/plugins/{name} Method url body description GET /apisix/admin/plugins/list NULL Fetches a list of all plugins without properties GET /apisix/admin/plugins/{name} NULL Fetches the plugin with the given name Request Parameters Parameter Required Description Example subsystem false Plugin(s) will be searched only for the given subsystem. /apisix/admin/plugins/http-logger?subsystem=http will search http-logger plugin in http subsystems only 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 Deprecating ?all=true 3.1 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 will be no breaking change. 3.2 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 assumes to only get L7 plugins, after this change they will have to add subsystem=http to make things explicit. 3.3. 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.
