juzhiyuan commented on a change in pull request #6565: URL: https://github.com/apache/apisix/pull/6565#discussion_r824523469
########## File path: docs/en/latest/admin-api.md ########## @@ -21,75 +21,68 @@ title: Admin API # --> -## Description +The Admin API lets users control their deployed Apache APISIX instance. The [architecture design](./architecture-design/apisix.md) gives an idea about how everything fits together. -The Admin API is a group of APIs served for the Apache APISIX, we could pass parameters to APIs to control APISIX Nodes. To have a better understanding about how it works, please see [the architecture design](./architecture-design/apisix.md). +By default, the Admin API listens to port `9080` (`9443` for HTTPS) when APISIX is launched. This can be changed by modifying your configuration file ([conf/config.yaml](https://github.com/apache/apisix/blob/master/conf/config.yaml)). -When Apache APISIX launches, the Admin API will listen on `9080` port by default (`9443` port for HTTPS). You could take another port by modifying the [conf/config.yaml](https://github.com/apache/apisix/blob/master/conf/config.yaml) file. - -The `X-API-KEY` appearing below refers to the `apisix.admin_key.key` in the `conf/config.yaml` file, which is the access token of the Admin API. +**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. ## Route -*API*：/apisix/admin/routes/{id}?ttl=0 +**API**: /apisix/admin/routes/{id}?ttl=0 -*Description*：Route matches requests based on preset rules, and loads the appropriate plugin according to the matching result, then forwarding requests to target Upstream. +[Routes](./architecture-design/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). -Note: When the `Admin API` is enabled, it will occupy the API prefixed with `/apisix/admin`. Therefore, in order to avoid conflicts between your design API and `/apisix/admin`, it is recommended to use a different port for the Admin API. You can customize the Admin API port through `port_admin` in `conf/config.yaml`. +**Note**: When the Admin API is enabled, to avoid conflicts with your design API, use a different port for the Admin API. This can be set in your configuration file by changing the `port_admin` key. ### Request Methods -| Method | Request URI | Request Body | Description | -| ------ | -------------------------------- | ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| GET | /apisix/admin/routes | NULL | Fetch resource list | -| GET | /apisix/admin/routes/{id} | NULL | Fetch resource | -| PUT | /apisix/admin/routes/{id} | {...} | Create resource by ID | -| POST | /apisix/admin/routes | {...} | Create resource, and ID is generated by server | -| DELETE | /apisix/admin/routes/{id} | NULL | Remove resource | -| PATCH | /apisix/admin/routes/{id} | {...} | Standard PATCH. Update some attributes of the existing Route, and other attributes not involved will remain as they are; if you want to delete an attribute, set the value of the attribute Set to null to delete; especially, when the value of the attribute is an array, the attribute will be updated in full | -| PATCH | /apisix/admin/routes/{id}/{path} | {...} | SubPath PATCH, specify the attribute of Route to be updated through {path}, update the value of this attribute in full, and other attributes that are not involved will remain as they are. The difference between the two PATCH can refer to the following examples | +| Method | Request URI | Request Body | Description | +| ------ | -------------------------------- | ------------ | ----------------------------------------------------------------------------------------------------------------------------- | +| GET | /apisix/admin/routes | NULL | Fetches a list of all configured Routes. list | Review comment: I would prefer removing the `list` currently because your description is clearer. 😉 ########## File path: docs/en/latest/admin-api.md ########## @@ -276,44 +269,46 @@ After successful execution, status nodes will be updated to: ### Response Parameters -Return response from etcd currently. +Currently, the response is returned from etcd. [Back to TOC](#table-of-contents) ## Service -*API*：/apisix/admin/services/{id} +**API**: /apisix/admin/services/{id} + +A Service is an abstraction of an API (which can also be understood as a set of Route abstractions). It usually corresponds to an upstream service abstraction. -*Description*：A `Service` is an abstraction of an API (which can also be understood as a set of Route abstractions). It usually corresponds to the upstream service abstraction. Between `Route` and `Service`, usually the relationship of N:1. +The relationship between Routes and a Service is usually N:1. ### Request Methods -| Method | Request URI | Request Body | Description | -| ------ | ---------------------------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| GET | /apisix/admin/services | NULL | Fetch resource list | -| GET | /apisix/admin/services/{id} | NULL | Fetch resource | -| PUT | /apisix/admin/services/{id} | {...} | Create resource by ID | -| POST | /apisix/admin/services | {...} | Create resource, and ID is generated by server | -| DELETE | /apisix/admin/services/{id} | NULL | Remove resource | -| PATCH | /apisix/admin/services/{id} | {...} | Standard PATCH. Update some attributes of the existing Service, and other attributes not involved will remain as they are; if you want to delete an attribute, set the value of the attribute Set to null to delete; especially, when the value of the attribute is an array, the attribute will be updated in full | -| PATCH | /apisix/admin/services/{id}/{path} | {...} | SubPath PATCH, specify the attribute of Service to be updated through {path}, update the value of this attribute in full, and other attributes that are not involved will remain as they are. The difference between the two PATCH can refer to the following examples | +| Method | Request URI | Request Body | Description | +| ------ | ---------------------------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------- | +| GET | /apisix/admin/services | NULL | Fetches a list of available Services. | +| GET | /apisix/admin/services/{id} | NULL | Fetches specified Service by id. | +| PUT | /apisix/admin/services/{id} | {...} | Creates a Service with the specified id. | +| POST | /apisix/admin/services | {...} | Creates a Service and assigns an id. | Review comment: How about using `random id` and `specified id`? ########## File path: docs/en/latest/admin-api.md ########## @@ -21,75 +21,68 @@ title: Admin API # --> -## Description +The Admin API lets users control their deployed Apache APISIX instance. The [architecture design](./architecture-design/apisix.md) gives an idea about how everything fits together. -The Admin API is a group of APIs served for the Apache APISIX, we could pass parameters to APIs to control APISIX Nodes. To have a better understanding about how it works, please see [the architecture design](./architecture-design/apisix.md). +By default, the Admin API listens to port `9080` (`9443` for HTTPS) when APISIX is launched. This can be changed by modifying your configuration file ([conf/config.yaml](https://github.com/apache/apisix/blob/master/conf/config.yaml)). -When Apache APISIX launches, the Admin API will listen on `9080` port by default (`9443` port for HTTPS). You could take another port by modifying the [conf/config.yaml](https://github.com/apache/apisix/blob/master/conf/config.yaml) file. - -The `X-API-KEY` appearing below refers to the `apisix.admin_key.key` in the `conf/config.yaml` file, which is the access token of the Admin API. +**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. ## Route -*API*：/apisix/admin/routes/{id}?ttl=0 +**API**: /apisix/admin/routes/{id}?ttl=0 -*Description*：Route matches requests based on preset rules, and loads the appropriate plugin according to the matching result, then forwarding requests to target Upstream. +[Routes](./architecture-design/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). -Note: When the `Admin API` is enabled, it will occupy the API prefixed with `/apisix/admin`. Therefore, in order to avoid conflicts between your design API and `/apisix/admin`, it is recommended to use a different port for the Admin API. You can customize the Admin API port through `port_admin` in `conf/config.yaml`. +**Note**: When the Admin API is enabled, to avoid conflicts with your design API, use a different port for the Admin API. This can be set in your configuration file by changing the `port_admin` key. ### Request Methods -| Method | Request URI | Request Body | Description | -| ------ | -------------------------------- | ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| GET | /apisix/admin/routes | NULL | Fetch resource list | -| GET | /apisix/admin/routes/{id} | NULL | Fetch resource | -| PUT | /apisix/admin/routes/{id} | {...} | Create resource by ID | -| POST | /apisix/admin/routes | {...} | Create resource, and ID is generated by server | -| DELETE | /apisix/admin/routes/{id} | NULL | Remove resource | -| PATCH | /apisix/admin/routes/{id} | {...} | Standard PATCH. Update some attributes of the existing Route, and other attributes not involved will remain as they are; if you want to delete an attribute, set the value of the attribute Set to null to delete; especially, when the value of the attribute is an array, the attribute will be updated in full | -| PATCH | /apisix/admin/routes/{id}/{path} | {...} | SubPath PATCH, specify the attribute of Route to be updated through {path}, update the value of this attribute in full, and other attributes that are not involved will remain as they are. The difference between the two PATCH can refer to the following examples | +| Method | Request URI | Request Body | Description | +| ------ | -------------------------------- | ------------ | ----------------------------------------------------------------------------------------------------------------------------- | +| GET | /apisix/admin/routes | NULL | Fetches a list of all configured Routes. list | +| GET | /apisix/admin/routes/{id} | NULL | Fetches specified Route by id. | +| PUT | /apisix/admin/routes/{id} | {...} | Creates a Route with the specified id. | +| POST | /apisix/admin/routes | {...} | Creates a Route and assigns an id. | Review comment: ```suggestion | POST | /apisix/admin/routes | {...} | Creates a Route and assigns an random id. | ``` -- 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]
