Sent from my iPhone
> On Jun 14, 2022, at 22:26, Kwanhur Huang <huang_hua2...@163.com> wrote:
>
> Really Looking forward!!
>
> Question: what about the new Admin API backward compatibility?
>
> Kwanhur Huang
> TL;DR
>
>> 2022年6月14日 上午11:51，tzssangglass <tzssanggl...@apache.org> 写道：
>>
>> 1. Background
>>
>> The new API design for the Admin API, which no longer relies on the etcd
>> data format. The current API design of Admin API, is no design, we use the
>> HTTP RESTful API of etcd v2 directly. It is not good for API Gateway case.
>> Here are some reasons:
>> 1. Not support paging when fetching object list
>> 2. Not support filters when fetching object list
>> 3. The APISIX users need the route data, they don't care how it is stored.
>>
>> 1.1 Problem to be solved
>>
>> The Admin API use the HTTP API of etcd v2 REST. It has been deprecated by
>> etcd. As APISIX grows, users expect the Admin API to be more powerful and
>> clear:
>> 1. We need a more standardized and easy-to-understand Admin API interface.
>> 2. Remove strong dependency on etcd data format.
>> 3. Support pagination, search and other functions, making it easier for
>> users to find the APISIX data they need.
>>
>> 1.2 The benefits of solving this problem
>>
>> When fetching data of different types:
>> 1. Support paging to fetch data to avoid the response body being too large
>> due to a large number of certain types of data.
>> 2. Remove the outermost nesting to make the response data structure simpler.
>> 3. Support filtering by name, label, etc., allows the user to find the data
>> content that users are interested in quickly.
>>
>>
>> 2. How to solve the problem
>>
>> 2.1 List of URIs that need to be updated
>>
>> 2.1.1 For SSL objects, the plural form should be used
>>
>> API design: /apisix/admin/ssls/{id}
>>
>> examples of put a ssl object:
>>
>> ```
>> curl http://127.0.0.1:9080/apisix/admin/ssls/1 -X PUT -d {
>> "cert": ... ...,
>> "key": ... ...,
>> "snis": ["foo.com"],
>> }
>> ```
>>
>> examples of fetch ssl objects
>>
>> ```
>> curl http://127.0.0.1:9080/apisix/admin/ssls
>>
>> {
>> "count": 2,
>> "list": [
>> {...},
>> {...},
>> ]
>> }
>> ```
>>
>> 2.1.2 For proto objects, the plural form should be used
>>
>> API design: /apisix/admin/protos/{id}
>>
>> examples of put a proto object:
>>
>> ```
>> curl http://127.0.0.1:9080/apisix/admin/protos/1 -X PUT -d {
>> ... ...
>> }
>>
>> ```
>>
>> examples of fetch proto objects:
>>
>> ```
>> curl http://127.0.0.1:9080/apisix/admin/protos
>>
>> {
>> "count": 2,
>> "list": [
>> {...},
>> {...},
>> ]
>> }
>> ```
>>
>> 2.2 Response body format
>>
>> 2.2.1 Remove action field in response body, it is useless
>>
>> 2.2.2 Make the response body format simpler for list of object
>>
>> fetch object, return the object information directly, examples:
>>
>> ```
>> curl http://127.0.0.1:9080/apisix/admin/routes/12
>> {
>> "key": "/apisix/routes/12",
>> "createdIndex": 1655,
>> "value": {
>> "id": "12",
>> "uri": "/hello",
>> "create_time": 1653964280,
>> "status": 1,
>> "upstream": {
>> "type": "roundrobin",
>> "pass_host": "pass",
>> "hash_on": "vars",
>> "nodes": {
>> "127.0.0.1:1980": 1
>> },
>> "scheme": "http"
>> },
>> "update_time": 1654519342
>> },
>> "modifiedIndex": 2289
>> }
>> ```
>>
>>
>> fetch object list, return `count` and `list` field. Each item in the list
>> is the object(eg: route, service or upstream), examples:
>>
>> ```
>> curl http://127.0.0.1:9080/apisix/admin/routes -H 'X-API-KEY:
>> edd1c9f034335f136f87ad84b625c8f1'
>> {
>> "count": 2,
>> "list": [
>> {
>> "createdIndex": 1655,
>> "key": "/apisix/routes/1",
>> "value": {
>> "id": "1",
>> "priority": 0,
>> "uri": "/hello",
>> "create_time": 1649143475,
>> "upstream": {
>> "type": "roundrobin",
>> "pass_host": "pass",
>> "hash_on": "vars",
>> "nodes": {
>> "127.0.0.1:1980": 1
>> },
>> "scheme": "http"
>> },
>> "update_time": 1653963881,
>> "status": 1
>> },
>> "modifiedIndex": 2289
>> },
>> {
>> "createdIndex": 2290,
>> "key": "/apisix/routes/12",
>> "value": {
>> "id": "12",
>> "priority": 0,
>> "uri": "/hello",
>> "create_time": 1653964280,
>> "status": 1,
>> "upstream": {
>> "type": "roundrobin",
>> "pass_host": "pass",
>> "hash_on": "vars",
>> "nodes": {
>> "127.0.0.1:1980": 1
>> },
>> "scheme": "http"
>> },
>> "update_time": 1654519342
>> },
>> "modifiedIndex": 2325
>> }
>> ]
>> }
>> ```
>>
>> 2.3 New feature for all Admin APIs
>>
>> 2.3.1 Supports paging to get a list of objects such as route
>>
>> Avoid being unable to return all objects in a single request because there
>> are too many objects of a specific type.
>>
>> More friendly to web applications. For administrators, the number of list
>> displayed on a single page is usually between 20 and 50.
>>
>> - Feature: support new query arguments:
>> - page: the current page number, the default value is 1, and the valid
>> value is a positive integer.
>> - page_size: the page size, no paging by default, the valid value should
>> be from 10 to 500.
>>
>> examples:
>>
>> ```
>> curl http://xxxx/apisix/admin/routes?page=1&page_size=10
>>
>> {
>> "count": 1,
>> "list": [
>> {
>> ... ...
>> }
>> ]
>> }
>> ```
>>
>> - Object list that need to support paging:
>> routes
>> services
>> upstreams
>> consumers
>> schema
>> ssls
>> protos
>> global_rules
>> stream_routes
>> plugin_metadata
>> plugin_configs
>>
>> Note:
>> The paging will be done on APISIX, not lua-resty-etcd.
>> APISIX will do some of the following:
>> 1. get all routes data from memory (instead of querying from etcd)
>> 2. sort all routes by update_time, the larger the update_time, the higher
>> the ranking(sorted by update_time in descending order)
>> 3. get the corresponding routes according to the paging parameter
>> 4. if there are no paging parameters, follow the default values in the
>> requirements.
>> 5. return the paging parameters of the query in the response.
>>
>>
>> 2.2 Supports filter when get a list of objects such as route
>>
>> - Feature: filter fields supported by all objects
>> - name: If the object's name contains the name string specified by the
>> user, the matching result is true; otherwise the matching result is false.
>> - label: If the object's label is the same as the label specified by the
>> user, the matching result is true; otherwise the matching result is false.
>> - Feature: additional filter fields supported by the Route object
>> - uri: If the route's uri contains the uri string specified by the user,
>> the matching result is true; otherwise the matching result is false.
>>
>> When the user has enabled multiple filter fields, there is an and
>> relationship between the different fields. For example, the following
>> example is expected to return a list of routes: the route's name contains
>> the string "test", and the URI contains the string "foo". There is no
>> restriction on the route label because the input is an empty string.
>>
>> examples:
>>
>> ```
>> curl http://xxxx/apisix/admin/routes?name=test&uri=foo&label=
>>
>> {
>> "count": 1,
>> "list": [
>> {...}
>> ]
>> }
>> ```
>>
>> - Object list that need to support paging:
>> routes
>> services
>> upstreams
>> consumers
>> schema
>> ssls
>> protos
>> global_rules
>> stream_routes
>> plugin_metadata
>> plugin_configs
>>
>> *ZhengSong Tu*
>> My GitHub: https://github.com/tzssangglass
>> Apache APISIX: https://github.com/apache/apisix
>
