You are viewing a plain text version of this content. The canonical link for it is here.
Posted to notifications@apisix.apache.org by ju...@apache.org on 2022/08/12 07:54:39 UTC
[apisix] branch master updated: docs: introduce the paging and filtering (#7647)
This is an automated email from the ASF dual-hosted git repository.
juzhiyuan pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/apisix.git
The following commit(s) were added to refs/heads/master by this push:
new 5bdcd4412 docs: introduce the paging and filtering (#7647)
5bdcd4412 is described below
commit 5bdcd4412025877b15ea71510be13ebfca52d220
Author: tzssangglass <tz...@gmail.com>
AuthorDate: Fri Aug 12 15:54:33 2022 +0800
docs: introduce the paging and filtering (#7647)
---
docs/en/latest/admin-api.md | 86 +++++++++++++++++++++++++++++++++++++++++++++
docs/zh/latest/admin-api.md | 85 ++++++++++++++++++++++++++++++++++++++++++++
2 files changed, 171 insertions(+)
diff --git a/docs/en/latest/admin-api.md b/docs/en/latest/admin-api.md
index 9889c1be9..8193f6152 100644
--- a/docs/en/latest/admin-api.md
+++ b/docs/en/latest/admin-api.md
@@ -27,6 +27,92 @@ By default, the Admin API listens to port `9080` (`9443` for HTTPS) when APISIX
**Note**: Mentions of `X-API-KEY` in this document refers to `apisix.admin_key.key`—the access token for Admin API—in your configuration file.
+## V3
+
+The Admin API has made some breaking changes in V3 version, as well as supporting additional features.
+
+### Support new response body format
+
+1. Remove `action` field in response body;
+2. Adjust the response body structure when fetching the list of resources, the new response body structure like:
+
+```json
+{
+ "count":2,
+ "list":[
+ {
+ ...
+ },
+ {
+ ...
+ }
+ ]
+}
+```
+
+### Support paging query
+
+Paging query is supported when getting the resource list, paging parameters include:
+
+| parameter | Default | Valid range | Description |
+| --------- | ------ | ----------- | ---------------------------- |
+| page | 1 | [1, ...] | Number of pages |
+| page_size | | [10, 500] | Number of resources per page |
+
+The example is as follows:
+
+```shell
+$ curl http://127.0.0.1:9080/apisix/admin/routes?page=1&page_size=10 \
+-H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -i -d '
+{
+ "count": 1,
+ "list": [
+ {
+ ...
+ }
+ ]
+}
+```
+
+Resources that support paging queries:
+
+- Consumer
+- Global Rules
+- Plugin Config
+- Proto
+- Route
+- Service
+- SSL
+- Stream Route
+- Upstream
+
+### Support filtering query
+
+When getting a list of resources, it supports filtering resources based on `name`, `label`, `uri`.
+
+| parameter | parameter |
+| --------- | ------------------------------------------------------------ |
+| name | Query resource by their `name`, which will not appear in the query results if the resource itself does not have `name`. |
+| label | Query resource by their `label`, which will not appear in the query results if the resource itself does not have `label`. |
+| uri | Supported on Route resources only. If the `uri` of a Route is equal to the uri of the query or if the `uris` contains the uri of the query, the Route resource appears in the query results. |
+
+When multiple filter parameters are enabled, use the intersection of the query results for different filter parameters.
+
+The following example will return a list of routes, and all routes in the list satisfy: the `name` of the route contains the string "test", the `uri` contains the string "foo", and there is no restriction on the `label` of the route, since the label of the query is the empty string.
+
+```shell
+$ curl http://127.0.0.1:9080/apisix/admin/routes?name=test&uri=foo&label= \
+-H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -i -d '
+{
+ "count": 1,
+ "list": [
+ {
+ ...
+ }
+ ]
+}
+```
+
## Route
**API**: /apisix/admin/routes/{id}?ttl=0
diff --git a/docs/zh/latest/admin-api.md b/docs/zh/latest/admin-api.md
index 7f7668e23..a5a2dffaa 100644
--- a/docs/zh/latest/admin-api.md
+++ b/docs/zh/latest/admin-api.md
@@ -29,6 +29,91 @@ Admin API 是为 Apache APISIX 服务的一组 API，我们可以将参数传递
在下面出现的 `X-API-KEY` 指的是 `conf/config.yaml` 文件中的 `apisix.admin_key.key`，它是 Admin API 的访问 token。
+## V3
+
+Admin API 在 V3 版本中做了一些不向下兼容的调整，以及支持更多特性。
+
+### 支持新的响应体格式
+
+1. 移除响应体中的 `action` 字段；
+2. 调整获取资源列表时的响应体结构，新的响应体结构示例如下：
+
+```json
+{
+ "count":2,
+ "list":[
+ {
+ ...
+ },
+ {
+ ...
+ }
+ ]
+}
+```
+
+### 支持分页查询
+
+获取资源列表时支持分页查询，分页参数包括：
+
+| 参数 | 默认值 | 范围 | 说明 |
+| --------- | ------ | -------- | ------------ |
+| page | 1 | [1, ...] | 页数 |
+| page_size | | [10, 500]| 每页资源数量 |
+
+示例如下：
+
+```shell
+$ curl http://127.0.0.1:9080/apisix/admin/routes?page=1&page_size=10 \
+-H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -i -d '
+{
+ "count": 1,
+ "list": [
+ {
+ ...
+ }
+ ]
+}
+```
+
+目前支持分页查询的资源如下：
+
+- Consumer
+- Global Rules
+- Plugin Config
+- Proto
+- Route
+- Service
+- SSL
+- Stream Route
+- Upstream
+
+### 支持过滤资源
+
+获取资源列表时支持根据 `name`, `label`, `uri` 过滤资源。
+
+| 参数 | 说明 |
+| ----- | --------------------------------------------------------------------------------------------------- |
+| name | 根据资源的 `name` 属性进行查询，如果资源本身没有 `name` 属性则不会出现在查询结果中。 |
+| label | 根据资源的 `label` 属性进行查询，如果资源本身没有 `labe`l 属性则不会出现在查询结果中。 |
+| uri | 仅在 Route 资源上支持。如果 Route 的 `uri` 等于查询的 uri 或 `uris` 包含查询的 uri，则该 Route 资源出现在查询结果中。 |
+
+当启用了多个过滤参数时，对不同过滤参数的查询结果取交集。
+下述示例将返回一个路由列表，该路由列表中的所有路由满足以下条件：路由的 `name` 包含字符串 "test"；`uri` 包含字符串 "foo"；对路由的 `label` 没有限制，因为查询的 label 是空字符串。
+
+```shell
+$ curl http://127.0.0.1:9080/apisix/admin/routes?name=test&uri=foo&label= \
+-H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -i -d '
+{
+ "count": 1,
+ "list": [
+ {
+ ...
+ }
+ ]
+}
+```
+
## Route
*地址*：/apisix/admin/routes/{id}?ttl=0