You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@apisix.apache.org by Ashish Tiwari <as...@gmail.com> on 2023/06/22 14:12:06 UTC

Proposal: Refactoring Admin API for Plugins resource

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.