liuxiran opened a new issue #2105: URL: https://github.com/apache/apisix-dashboard/issues/2105
# Route restful API proposal According to our discussion on mail list: https://lists.apache.org/thread.html/r29f4b901d9779349bfcc3516f8f15ad73506bc16c3c3600666cbf7ef%40%3Cdev.apisix.apache.org%3E I tried to list the entire Route module API in detail, and the goal is to serve as a sample of modifications to other modules, here they are: ### Create route #### Method and URL ```text POST /apisix/admin/routes ``` #### Request parameters | name | type | In | required | description | | ----------- | ------- | -------- | -------- | ------------------------------------------- | | X-API-KEY | string | Header | true | access token got by login | and other request body parameters, please refer to https://github.com/apache/apisix/blob/master/docs/en/latest/admin-api.md#request-body-parameters **notice** * only keep `uris`, remove `uri`, since `uris` contains `uri`, there is no need to keep two of them to Increase the difficulty of choice for users * only keep `hosts`, remove `host`, same reason with before * only keep `remote_addrs`, remove `remote_addr`, same reason with before * should not accept `create_time` and `update_time` from the request * only keep `POST` method to create a route, remove `PUT`(`PUT /apisix/admin/routes/{id}`) to reduce the difficulty of choice for users #### Response parameters ```text Status: 200 OK ``` return the new created route info ```json { "id":"368819495659307851", "create_time":1629363150, "update_time":1630332911, "uri":"/libraries/jquery", "name":"CDN", "methods":["GET"], "vars":[["http_fff","==","fff"]], "plugins":{}, "upstream":{"nodes":[{"host":"api.cdnjs.com","port":443,"weight":1}],"retries":1,"timeout":{"connect":6,"read":6,"send":6}, "type":"roundrobin", "scheme":"https", "pass_host":"node", "labels": {"0":"npm","API_VERSION":"1.0"}, "status":0 } ``` ```text Status: 400 Bad Request ``` ```json { "message": "error details" } ``` ```text Status: 401 Unauthorized ``` ```json { "message": "error details" } ``` ```text Status: 500 Internal Server Error ``` ```json { "message": "error details" } ``` ### Fetch routes list #### Method and URL ```text GET /apisix/admin/routes ``` #### Request parameters | name | type | In | required | description | | ----------- | ------- | -------- | -------- | ------------------------------------------- | | page | int | Query | false | search route by pagination：page index | | page_size | int | Query | false | query the number of routes per page | | name | string | Query | false | search route by name. | | uri | string | Query | false | search route by uri. ｜ | status | string | Query | false | route status, `1` for enabled, `0` for disable。 | | labels | string | Query | false | search route by labels | | X-API-KEY | string | Header | true | access token got by login | **notice** this part has two changes: * change `label` to `labels`, for `labels` is the field name, and we support searching route with multi labels. * change `Authorization ` to `X-API-KEY` to achieve the authentication. #### Response parameters ```text Status: 200 OK ``` ```json { "items":[{ "id":"368819495659307851", "create_time":1629363150, "update_time":1630332911, "uri":"/libraries/jquery", "name":"CDN", "methods":["GET"], "vars":[["http_fff","==","fff"]], "plugins":{}, "upstream":{"nodes":[{"host":"api.cdnjs.com","port":443,"weight":1}],"retries":1,"timeout":{"connect":6,"read":6,"send":6}, "type":"roundrobin", "scheme":"https", "pass_host":"node", "labels": {"0":"npm","API_VERSION":"1.0"}, "status":0 }], "total_size": 1, } ``` ```text Status: 401 Unauthorized ``` ```json { "message": "error details" } ``` ```text Status: 500 Internal Server Error ``` ```json { "message": "error details" } ``` ### Get route info #### Method and URL ```text GET /apisix/admin/routes/{id} ``` #### Request parameters | name | type | In | required | description | | ----------- | ------- | -------- | -------- | ------------------------------------------- | | id | string | Query | true | route id | | X-API-KEY | string | Header | true | access token got by login | #### Response parameters ```text Status: 200 OK ``` ```json { "id":"368819495659307851", "create_time":1629363150, "update_time":1630332911, "uri":"/libraries/jquery", "name":"CDN", "methods":["GET"], "vars":[["http_fff","==","fff"]], "plugins":{}, "upstream":{"nodes":[{"host":"api.cdnjs.com","port":443,"weight":1}],"retries":1,"timeout":{"connect":6,"read":6,"send":6}, "type":"roundrobin", "scheme":"https", "pass_host":"node", "labels": {"0":"npm","API_VERSION":"1.0"}, "status":0 } ``` ```text Status: 404 Not Found ``` ```json { "message": "Not found" } ``` ```text Status: 401 Unauthorized ``` ```json { "message": "error details" } ``` ```text Status: 500 Internal Server Error ``` ```json { "message": "error details" } ``` ### Update route info #### Method and URL ```text PATCH /apisix/admin/routes/{id} ``` #### Request parameters | name | type | In | required | description | | ----------- | ------- | -------- | -------- | ------------------------------------------- | | id | string | Query | true | route id | | X-API-KEY | string | Header | true | access token got by login | and other request body parameters, please refer to https://github.com/apache/apisix/blob/master/docs/en/latest/admin-api.md#request-body-parameters, and the same notice with create route #### Response parameters ```text Status: 200 OK ``` return the updated route info ```json { "id":"368819495659307851", "create_time":1629363150, "update_time":1630332911, "uri":"/libraries/jquery", "name":"CDN", "methods":["GET"], "vars":[["http_fff","==","fff"]], "plugins":{}, "upstream":{"nodes":[{"host":"api.cdnjs.com","port":443,"weight":1}],"retries":1,"timeout":{"connect":6,"read":6,"send":6}, "type":"roundrobin", "scheme":"https", "pass_host":"node", "labels": {"0":"npm","API_VERSION":"1.0"}, "status":0 } ``` ```text Status: 400 Bad Request ``` ```json { "message": "xxxx" } ``` ```text Status: 401 Unauthorized ``` ```json { "message": "error details" } ``` ```text Status: 500 Internal Server Error ``` ```json { "message": "error details" } ``` ### Delete route #### Method and URL ```text DELETE /apisix/admin/routes/{id} ``` #### Request parameters | name | type | In | required | description | | ----------- | ------- | -------- | -------- | ------------------------------------------- | | id | string | Query | true | route id | | X-API-KEY | string | Header | true | access token got by login | #### Response parameters ```text Status: 200 OK ``` return the deleted route info ```json { "id":"368819495659307851", "create_time":1629363150, "update_time":1630332911, "uri":"/libraries/jquery", "name":"CDN", "methods":["GET"], "vars":[["http_fff","==","fff"]], "plugins":{}, "upstream":{"nodes":[{"host":"api.cdnjs.com","port":443,"weight":1}],"retries":1,"timeout":{"connect":6,"read":6,"send":6}, "type":"roundrobin", "scheme":"https", "pass_host":"node", "labels": {"0":"npm","API_VERSION":"1.0"}, "status":0 } ``` ```text Status: 400 Bad Request ``` ```json { "message": "xxxx" } ``` ```text Status: 401 Unauthorized ``` ```json { "message": "error details" } ``` ```text Status: 500 Internal Server Error ``` ```json { "message": "error details" } ``` ### Update specify property #### Method and URL ```text PUT /apisix/admin/routes/{id}/{path} ``` **notice** * I prefer to use `PUT` method instead of `PATCH`, reason: this API aimed to update the specify property avoid entering the entire parameter structure in the body, and can only update the property defined in path parameters, so `PUT` is more suitable. #### Request parameters | name | type | In | required | description | | ----------- | ------- | -------- | -------- | ------------------------------------------- | | X-API-KEY | string | Header | true | access token got by login | and the specify property values. #### Response parameters ```text Status: 200 OK ``` return the updated route info ```json { "id":"368819495659307851", "create_time":1629363150, "update_time":1630332911, "uri":"/libraries/jquery", "name":"CDN", "methods":["GET"], "vars":[["http_fff","==","fff"]], "plugins":{}, "upstream":{"nodes":[{"host":"api.cdnjs.com","port":443,"weight":1}],"retries":1,"timeout":{"connect":6,"read":6,"send":6}, "type":"roundrobin", "scheme":"https", "pass_host":"node", "labels": {"0":"npm","API_VERSION":"1.0"}, "status":0 } ``` ```text Status: 400 Bad Request ``` ```json { "message": "xxxx" } ``` ```text Status: 401 Unauthorized ``` ```json { "message": "error details" } ``` ```text Status: 500 Internal Server Error ``` ```json { "message": "error details" } ``` -- 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: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
