You are viewing a plain text version of this content. The canonical link for it is here.
Posted to notifications@apisix.apache.org by GitBox <gi...@apache.org> on 2022/08/11 08:10:47 UTC
[GitHub] [apisix] SylviaBABY commented on a diff in pull request #7647: docs: introduce the paging and filtering
SylviaBABY commented on code in PR #7647:
URL: https://github.com/apache/apisix/pull/7647#discussion_r943203260
##########
docs/en/latest/admin-api.md:
##########
@@ -27,6 +27,90 @@ 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, as well as supporting additional features.
Review Comment:
```suggestion
The Admin API has made some breaking changes in V3 version, as well as supporting additional features.
```
##########
docs/zh/latest/admin-api.md:
##########
@@ -29,6 +29,89 @@ 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 '
Review Comment:
```suggestion
curl http://127.0.0.1:9080/apisix/admin/routes?page=1&page_size=10 \
-H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -i -d '
```
##########
docs/en/latest/admin-api.md:
##########
@@ -27,6 +27,90 @@ 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, as well as supporting additional features.
+
+### 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":[
+ {
+ ...
+ },
+ {
+ ...
+ }
+ ]
+}
+```
+
+### Paging
+
+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 |
+
+e.g.
+
+```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
+
+### Filter
+
+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 '
Review Comment:
```suggestion
curl http://127.0.0.1:9080/apisix/admin/routes?name=test&uri=foo&label= \
-H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -i -d '
```
##########
docs/en/latest/admin-api.md:
##########
@@ -27,6 +27,90 @@ 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, as well as supporting additional features.
+
+### 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":[
+ {
+ ...
+ },
+ {
+ ...
+ }
+ ]
+}
+```
+
+### Paging
+
+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 |
+
+e.g.
+
+```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 '
Review Comment:
```suggestion
curl http://127.0.0.1:9080/apisix/admin/routes?page=1&page_size=10 \
-H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -i -d '
```
##########
docs/zh/latest/admin-api.md:
##########
@@ -29,6 +29,89 @@ 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": [
+ {
+ ...
+ }
+ ]
+}
+```
+
+支持分页查询的资源：
Review Comment:
```suggestion
目前支持分页查询的资源如下：
```
##########
docs/zh/latest/admin-api.md:
##########
@@ -29,6 +29,89 @@ 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. 调整获取资源列表时的响应体结构，新的响应体结构示例：
Review Comment:
```suggestion
2. 调整获取资源列表时的响应体结构，新的响应体结构示例如下：
```
##########
docs/zh/latest/admin-api.md:
##########
@@ -29,6 +29,89 @@ 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 '
Review Comment:
```suggestion
curl http://127.0.0.1:9080/apisix/admin/routes?name=test&uri=foo&label= \
-H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -i -d '
```
##########
docs/en/latest/admin-api.md:
##########
@@ -27,6 +27,90 @@ 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, as well as supporting additional features.
+
+### 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":[
+ {
+ ...
+ },
+ {
+ ...
+ }
+ ]
+}
+```
+
+### Paging
+
+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 |
+
+e.g.
Review Comment:
```suggestion
The example is as follows:
```
##########
docs/zh/latest/admin-api.md:
##########
@@ -29,6 +29,89 @@ 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 | 每页资源数量 |
+
+示例：
Review Comment:
```suggestion
示例如下：
```
##########
docs/zh/latest/admin-api.md:
##########
@@ -29,6 +29,89 @@ 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 是空字符串
Review Comment:
```suggestion
下述示例将返回一个路由列表，该路由列表中的所有路由满足以下条件：路由的 `name` 包含字符串 "test"；`uri` 包含字符串 "foo"；对路由的 `label` 没有限制，因为查询的 label 是空字符串。
```
##########
docs/en/latest/admin-api.md:
##########
@@ -27,6 +27,90 @@ 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, as well as supporting additional features.
+
+### 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":[
+ {
+ ...
+ },
+ {
+ ...
+ }
+ ]
+}
+```
+
+### Paging
+
+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 |
+
+e.g.
+
+```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
+
+### Filter
+
+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
Review Comment:
```suggestion
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.
```
--
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: notifications-unsubscribe@apisix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org