feat: enhance admin api filter (#12291)

Co-authored-by: Traky Deng <trakydeng@gmail.com>

Author: bzp2010

apisix/admin/init.lua

@@ -250,10 +250,8 @@ local function run()
         else
             core.response.set_header("X-API-VERSION", "v2")
         end
-        if resource.need_v3_filter then
-            data = v3_adapter.filter(data)
-        end
 
+        data = v3_adapter.filter(data, resource)
         data = strip_etcd_resp(data)
 
         core.response.exit(code, data)

apisix/admin/resource.lua

@@ -25,10 +25,8 @@ local type = type
 
 
 local _M = {
-    need_v3_filter = true,
+    list_filter_fields = {},
 }
-
-
 local mt = {
     __index = _M
 }

apisix/admin/routes.lua

@@ -143,5 +143,9 @@ return resource.new({
     name = "routes",
     kind = "route",
     schema = core.schema.route,
-    checker = check_conf
+    checker = check_conf,
+    list_filter_fields = {
+        service_id = true,
+        upstream_id = true,
+    },
 })

apisix/admin/stream_routes.lua

@@ -73,5 +73,9 @@ return resource.new({
     kind = "stream route",
     schema = core.schema.stream_route,
     checker = check_conf,
-    unsupported_methods = {"patch"}
+    unsupported_methods = { "patch" },
+    list_filter_fields = {
+        service_id = true,
+        upstream_id = true,
+    },
 })

apisix/admin/v3_adapter.lua

@@ -15,16 +15,18 @@
 -- limitations under the License.
 --
 
+local type              = type
+local pairs             = pairs
+local tonumber          = tonumber
+local ngx               = ngx
+local re_find           = ngx.re.find
 local fetch_local_conf  = require("apisix.core.config_local").local_conf
 local try_read_attr     = require("apisix.core.table").try_read_attr
 local deepcopy          = require("apisix.core.table").deepcopy
 local log               = require("apisix.core.log")
 local request           = require("apisix.core.request")
 local response          = require("apisix.core.response")
 local table             = require("apisix.core.table")
-local tonumber          = tonumber
-local re_find           = ngx.re.find
-local pairs             = pairs
 
 local _M = {}
 
@@ -120,11 +122,43 @@ local function pagination(body, args)
 end
 
 
-local function filter(body, args)
-    if not args.name and not args.label and not args.uri then
-        return
+local function _filter(item, args, resource)
+    if not args.filter then
+        return true
+    end
+
+    local filters, err = ngx.decode_args(args.filter or "", 100)
+    if not filters then
+        log.error("failed to decode filter args: ", err)
+        return false
+    end
+
+    for key, value in pairs(filters) do
+        if not resource.list_filter_fields[key] then
+            log.warn("filter field '", key, "' is not supported by resource: ", resource.name)
+            goto CONTINUE
+        end
+
+        if not item[key] then
+            return false
+        end
+
+        if type(value) == "table" then
+            value = value[#value] -- get the last value in the table
+        end
+
+        if item[key] ~= value then
+            return false
+        end
+
+        ::CONTINUE::
     end
 
+    return true
+end
+
+
+local function filter(body, args, resource)
     for i = #body.list, 1, -1 do
         local name_matched = true
         local label_matched = true
@@ -168,14 +202,15 @@ local function filter(body, args)
             end
         end
 
-        if not name_matched or not label_matched or not uri_matched then
+        if not name_matched or not label_matched or not uri_matched
+                            or not _filter(body.list[i].value, args, resource) then
             table.remove(body.list, i)
         end
     end
 end
 
 
-function _M.filter(body)
+function _M.filter(body, resource)
     if not enable_v3() then
         return body
     end
@@ -194,7 +229,7 @@ function _M.filter(body)
 
     -- filter and paging logic for list query only
     if processed_body.list then
-        filter(processed_body, args)
+        filter(processed_body, args, resource)
 
         -- calculate the total amount of filtered data
         processed_body.total = processed_body.list and #processed_body.list or 0

docs/en/latest/admin-api.md

@@ -278,6 +278,42 @@ curl 'http://127.0.0.1:9180/apisix/admin/routes?name=test&uri=foo&label=' \
 }
 ```
 
+### Support reference filtering query
+
+:::note
+
+This feature was introduced in APISIX 3.13.0.
+
+APISIX supports querying routes and stream routes by `service_id` and `upstream_id`. Other resources or fields are not currently supported.
+
+:::
+
+When getting a list of resources, it supports a `filter` for filtering resources by filters.
+
+It is encoded in the following manner.
+
+```text
+filter=escape_uri(key1=value1&key2=value2)
+```
+
+The following example filters routes using `service_id`. Applying multiple filters simultaneously will return results that match all filter conditions.
+
+```shell
+curl 'http://127.0.0.1:9180/apisix/admin/routes?filter=service_id%3D1' \
+-H "X-API-KEY: $admin_key" -X GET
+```
+
+```json
+{
+  "total": 1,
+  "list": [
+    {
+      ...
+    }
+  ]
+}
+```
+
 ## Route
 
 [Routes](./terminology/route.md) match the client's request based on defined rules, loads and executes the corresponding [plugins](#plugin), and forwards the request to the specified [Upstream](#upstream).

docs/zh/latest/admin-api.md

@@ -284,6 +284,42 @@ curl 'http://127.0.0.1:9180/apisix/admin/routes?name=test&uri=foo&label=' \
 }
 ```
 
+### 支持引用过滤资源 {#support-reference-filtering-query}
+
+:::note
+
+这个特性于 APISIX 3.13.0 引入。
+
+APISIX 支持通过 `service_id` 和 `upstream_id` 查询路由和 Stream 路由。现在不支持其他资源或字段。
+
+:::
+
+在获取资源列表时，你可以使用 `filter` 参数过滤资源。
+
+它以以下方式编码：
+
+```text
+filter=escape_uri(key1=value1&key2=value2)
+```
+
+以下是一个使用 `service_id` 进行路由列表过滤的例子。当同时设置了多个过滤条件，结果将为它们的交集。
+
+```shell
+curl 'http://127.0.0.1:9180/apisix/admin/routes?filter=service_id%3D1' \
+-H "X-API-KEY: $admin_key" -X GET
+```
+
+```json
+{
+  "total": 1,
+  "list": [
+    {
+      ...
+    }
+  ]
+}
+```
+
 ## Route
 
 Route 也称之为路由，可以通过定义一些规则来匹配客户端的请求，然后根据匹配结果加载并执行相应的插件，并把请求转发给到指定 Upstream（上游）。