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/03/10 06:49:47 UTC
[GitHub] [apisix] navendu-pottekkat opened a new pull request #6565: [docs] update the API docs
navendu-pottekkat opened a new pull request #6565:
URL: https://github.com/apache/apisix/pull/6565
Signed-off-by: Navendu Pottekkat <na...@gmail.com>
Fixes #6534
This PR updates the API docs (Admin API and Control API).
This improves the readability and consistency of the documentation similar to other recent changes.
--
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
[GitHub] [apisix] navendu-pottekkat commented on a change in pull request #6565: docs: update the API docs
Posted by GitBox <gi...@apache.org>.
navendu-pottekkat commented on a change in pull request #6565:
URL: https://github.com/apache/apisix/pull/6565#discussion_r824489669
##########
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:
@moonming Using a list keeps it consistent with other items in the page even though there is only one item. It was a single item list before as well and I did not change it.
Should I move it out of the list or keep it as it is?
--
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
[GitHub] [apisix] 1502shivam-singh commented on a change in pull request #6565: docs: update the API docs
Posted by GitBox <gi...@apache.org>.
1502shivam-singh commented on a change in pull request #6565:
URL: https://github.com/apache/apisix/pull/6565#discussion_r823488584
##########
File path: docs/en/latest/admin-api.md
##########
@@ -427,37 +422,37 @@ After successful execution, upstream nodes will not retain the original data, an
### Response Parameters
-Return response from etcd currently.
+Currently, the response is returned from etcd.
[Back to TOC](#table-of-contents)
## Consumer
-*API*：/apisix/admin/consumers/{username}
+**API**: /apisix/admin/consumers/{username}
-*Description*：Consumers are consumers of certain types of services and can only be used in conjunction with a user authentication system. Consumer regards the `username` property as the identity, so only the HTTP `PUT` method is supported for creating a new consumer.
+Consumers are users of services and can only be used in conjunction with a user authentication system. A Consumer is identified by a `username` property. So, for creating a new Consumer, only the HTTP `PUT` method is supported.
### Request Methods
-| Method | Request URI | Request Body | Description |
-| ------ | ---------------------------------- | ------------ | --------------------------- |
-| GET | /apisix/admin/consumers | NULL | Fetch resource list |
-| GET | /apisix/admin/consumers/{username} | NULL | Fetch resource |
-| PUT | /apisix/admin/consumers | {...} | Create resource by username |
-| DELETE | /apisix/admin/consumers/{username} | NULL | Remove resource |
+| Method | Request URI | Request Body | Description |
+| ------ | ---------------------------------- | ------------ | ------------------------------------------------- |
+| GET | /apisix/admin/consumers | NULL | Fetches a list of all Consumers. |
+| GET | /apisix/admin/consumers/{username} | NULL | Fetches specified Consumer by username. |
+| PUT | /apisix/admin/consumers | {...} | Create new Consumer. |
+| DELETE | /apisix/admin/consumers/{username} | NULL | Removes the Consumer with the specified username. |
### Request Body Parameters
-| Parameter | Required | Type | Description | Example |
-| ----------- | -------- | ----------- | ------------------------------------------------------------------- | ------------------------------------------------ |
-| username | True | Name | Consumer name | |
-| plugins | False | Plugin | See [Plugin](architecture-design/plugin.md) for more | |
-| desc | False | Auxiliary | Identifies route names, usage scenarios, and more. | customer xxxx |
-| labels | False | Match Rules | Key/value pairs to specify attributes | {"version":"v2","build":"16","env":"production"} |
-| create_time | False | Auxiliary | epoch timestamp in second, will be created automatically if missing | 1602883670 |
-| update_time | False | Auxiliary | epoch timestamp in second, will be created automatically if missing | 1602883670 |
+| Parameter | Required | Type | Description | Example |
+| ----------- | -------- | ----------- | ------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------ |
+| username | True | Name | Name of the Consumer. | |
+| plugins | False | Plugin | Plugins that are executed during the request/response cycle. See [Plugin](architecture-design/plugin.md) for more. | |
+| desc | False | Auxiliary | Description of usage scenarios. | customer xxxx |
+| labels | False | Match Rules | Attributes of the Consumer specified as key-value pairs. | {"version":"v2","build":"16","env":"production"} |
+| create_time | False | Auxiliary | Epoch timestamp in second of the created time. If missing, this field will be populated automatically. | 1602883670 |
+| update_time | False | Auxiliary | Epoch timestamp in second of the updated time. If missing, this field will be populated automatically. | 1602883670 |
Review comment:
Same here
--
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
[GitHub] [apisix] 1502shivam-singh commented on a change in pull request #6565: docs: update the API docs
Posted by GitBox <gi...@apache.org>.
1502shivam-singh commented on a change in pull request #6565:
URL: https://github.com/apache/apisix/pull/6565#discussion_r823487991
##########
File path: docs/en/latest/admin-api.md
##########
@@ -427,37 +422,37 @@ After successful execution, upstream nodes will not retain the original data, an
### Response Parameters
-Return response from etcd currently.
+Currently, the response is returned from etcd.
[Back to TOC](#table-of-contents)
## Consumer
-*API*：/apisix/admin/consumers/{username}
+**API**: /apisix/admin/consumers/{username}
-*Description*：Consumers are consumers of certain types of services and can only be used in conjunction with a user authentication system. Consumer regards the `username` property as the identity, so only the HTTP `PUT` method is supported for creating a new consumer.
+Consumers are users of services and can only be used in conjunction with a user authentication system. A Consumer is identified by a `username` property. So, for creating a new Consumer, only the HTTP `PUT` method is supported.
### Request Methods
-| Method | Request URI | Request Body | Description |
-| ------ | ---------------------------------- | ------------ | --------------------------- |
-| GET | /apisix/admin/consumers | NULL | Fetch resource list |
-| GET | /apisix/admin/consumers/{username} | NULL | Fetch resource |
-| PUT | /apisix/admin/consumers | {...} | Create resource by username |
-| DELETE | /apisix/admin/consumers/{username} | NULL | Remove resource |
+| Method | Request URI | Request Body | Description |
+| ------ | ---------------------------------- | ------------ | ------------------------------------------------- |
+| GET | /apisix/admin/consumers | NULL | Fetches a list of all Consumers. |
+| GET | /apisix/admin/consumers/{username} | NULL | Fetches specified Consumer by username. |
+| PUT | /apisix/admin/consumers | {...} | Create new Consumer. |
+| DELETE | /apisix/admin/consumers/{username} | NULL | Removes the Consumer with the specified username. |
### Request Body Parameters
-| Parameter | Required | Type | Description | Example |
-| ----------- | -------- | ----------- | ------------------------------------------------------------------- | ------------------------------------------------ |
-| username | True | Name | Consumer name | |
-| plugins | False | Plugin | See [Plugin](architecture-design/plugin.md) for more | |
-| desc | False | Auxiliary | Identifies route names, usage scenarios, and more. | customer xxxx |
-| labels | False | Match Rules | Key/value pairs to specify attributes | {"version":"v2","build":"16","env":"production"} |
-| create_time | False | Auxiliary | epoch timestamp in second, will be created automatically if missing | 1602883670 |
-| update_time | False | Auxiliary | epoch timestamp in second, will be created automatically if missing | 1602883670 |
+| Parameter | Required | Type | Description | Example |
+| ----------- | -------- | ----------- | ------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------ |
+| username | True | Name | Name of the Consumer. | |
+| plugins | False | Plugin | Plugins that are executed during the request/response cycle. See [Plugin](architecture-design/plugin.md) for more. | |
+| desc | False | Auxiliary | Description of usage scenarios. | customer xxxx |
+| labels | False | Match Rules | Attributes of the Consumer specified as key-value pairs. | {"version":"v2","build":"16","env":"production"} |
+| create_time | False | Auxiliary | Epoch timestamp in second of the created time. If missing, this field will be populated automatically. | 1602883670 |
Review comment:
> Epoch timestamp in second of the created time.
I am bit confused on the framing of this sentence. How about this -
```suggestion
| create_time | False | Auxiliary | Epoch timestamp (in seconds) of the created time. If missing, this field will be populated automatically. | 1602883670 |
```
--
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
[GitHub] [apisix] juzhiyuan commented on a change in pull request #6565: docs: update the API docs
Posted by GitBox <gi...@apache.org>.
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: notifications-unsubscribe@apisix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [apisix] navendu-pottekkat commented on a change in pull request #6565: docs: update the API docs
Posted by GitBox <gi...@apache.org>.
navendu-pottekkat commented on a change in pull request #6565:
URL: https://github.com/apache/apisix/pull/6565#discussion_r824540680
##########
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:
Oh. I misread the message and did not see the actual `list` word. I will remove that.
##########
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:
Sure, I will make this change throughout.
##########
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:
+1
--
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
[GitHub] [apisix] navendu-pottekkat commented on pull request #6565: docs: update the API docs
Posted by GitBox <gi...@apache.org>.
navendu-pottekkat commented on pull request #6565:
URL: https://github.com/apache/apisix/pull/6565#issuecomment-1064005788
@1502shivam-singh @yzeng25 Made the suggested changes.
--
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
[GitHub] [apisix] 1502shivam-singh commented on a change in pull request #6565: docs: update the API docs
Posted by GitBox <gi...@apache.org>.
1502shivam-singh commented on a change in pull request #6565:
URL: https://github.com/apache/apisix/pull/6565#discussion_r823499487
##########
File path: docs/en/latest/control-api.md
##########
@@ -21,13 +21,12 @@ title: Control API
#
-->
-The control API can be used to
+In Apache APISIX, the control API is used to:
-* expose APISIX internal state
-* control the behavior of a single isolate APISIX data plane
+* Check the internal state of APISIX.
Review comment:
I believe `expose` is the right word here compared to check. If you consider it a bit to the negative side, then `interact` sounds better to me.
--
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
[GitHub] [apisix] spacewander merged pull request #6565: docs: update the API docs
Posted by GitBox <gi...@apache.org>.
spacewander merged pull request #6565:
URL: https://github.com/apache/apisix/pull/6565
--
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
[GitHub] [apisix] navendu-pottekkat commented on pull request #6565: docs: update the API docs
Posted by GitBox <gi...@apache.org>.
navendu-pottekkat commented on pull request #6565:
URL: https://github.com/apache/apisix/pull/6565#issuecomment-1064947382
@juzhiyuan @yzeng25 @moonming Made the suggested changes.
--
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
[GitHub] [apisix] 1502shivam-singh commented on a change in pull request #6565: docs: update the API docs
Posted by GitBox <gi...@apache.org>.
1502shivam-singh commented on a change in pull request #6565:
URL: https://github.com/apache/apisix/pull/6565#discussion_r823491611
##########
File path: docs/en/latest/admin-api.md
##########
@@ -467,9 +462,9 @@ Config Example:
}
```
-The binding authentication plug-in is a bit special. When it needs to be used in conjunction with the consumer, it needs to provide user name, password and other information; on the other hand, when it is bound with route / service, it does not require any parameters. Because at this time, it is based on the user request data to infer which consumer the user corresponds to.
+When bound to Routes or Services, the authentication Plugins infers the Consumer from the request and does not require any parameters. Whereas, while it is bound to a Consumer, username, password and other information needs to be provided.
Review comment:
```suggestion
When bound to a Route or Service, the Authentication plugin infers the Consumer from the request and does not require any parameters. Whereas, when bound to a Consumer, username, password and other information needs to be provided.
```
--
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
[GitHub] [apisix] yzeng25 commented on a change in pull request #6565: docs: update the API docs
Posted by GitBox <gi...@apache.org>.
yzeng25 commented on a change in pull request #6565:
URL: https://github.com/apache/apisix/pull/6565#discussion_r823497363
##########
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 specified id. |
Review comment:
```suggestion
| PUT | /apisix/admin/services/{id} | {...} | Creates a Service with a specified 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: notifications-unsubscribe@apisix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [apisix] navendu-pottekkat commented on a change in pull request #6565: docs: update the API docs
Posted by GitBox <gi...@apache.org>.
navendu-pottekkat commented on a change in pull request #6565:
URL: https://github.com/apache/apisix/pull/6565#discussion_r823665059
##########
File path: docs/en/latest/admin-api.md
##########
@@ -427,37 +422,37 @@ After successful execution, upstream nodes will not retain the original data, an
### Response Parameters
-Return response from etcd currently.
+Currently, the response is returned from etcd.
[Back to TOC](#table-of-contents)
## Consumer
-*API*：/apisix/admin/consumers/{username}
+**API**: /apisix/admin/consumers/{username}
-*Description*：Consumers are consumers of certain types of services and can only be used in conjunction with a user authentication system. Consumer regards the `username` property as the identity, so only the HTTP `PUT` method is supported for creating a new consumer.
+Consumers are users of services and can only be used in conjunction with a user authentication system. A Consumer is identified by a `username` property. So, for creating a new Consumer, only the HTTP `PUT` method is supported.
### Request Methods
-| Method | Request URI | Request Body | Description |
-| ------ | ---------------------------------- | ------------ | --------------------------- |
-| GET | /apisix/admin/consumers | NULL | Fetch resource list |
-| GET | /apisix/admin/consumers/{username} | NULL | Fetch resource |
-| PUT | /apisix/admin/consumers | {...} | Create resource by username |
-| DELETE | /apisix/admin/consumers/{username} | NULL | Remove resource |
+| Method | Request URI | Request Body | Description |
+| ------ | ---------------------------------- | ------------ | ------------------------------------------------- |
+| GET | /apisix/admin/consumers | NULL | Fetches a list of all Consumers. |
+| GET | /apisix/admin/consumers/{username} | NULL | Fetches specified Consumer by username. |
+| PUT | /apisix/admin/consumers | {...} | Create new Consumer. |
+| DELETE | /apisix/admin/consumers/{username} | NULL | Removes the Consumer with the specified username. |
### Request Body Parameters
-| Parameter | Required | Type | Description | Example |
-| ----------- | -------- | ----------- | ------------------------------------------------------------------- | ------------------------------------------------ |
-| username | True | Name | Consumer name | |
-| plugins | False | Plugin | See [Plugin](architecture-design/plugin.md) for more | |
-| desc | False | Auxiliary | Identifies route names, usage scenarios, and more. | customer xxxx |
-| labels | False | Match Rules | Key/value pairs to specify attributes | {"version":"v2","build":"16","env":"production"} |
-| create_time | False | Auxiliary | epoch timestamp in second, will be created automatically if missing | 1602883670 |
-| update_time | False | Auxiliary | epoch timestamp in second, will be created automatically if missing | 1602883670 |
+| Parameter | Required | Type | Description | Example |
+| ----------- | -------- | ----------- | ------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------ |
+| username | True | Name | Name of the Consumer. | |
+| plugins | False | Plugin | Plugins that are executed during the request/response cycle. See [Plugin](architecture-design/plugin.md) for more. | |
+| desc | False | Auxiliary | Description of usage scenarios. | customer xxxx |
+| labels | False | Match Rules | Attributes of the Consumer specified as key-value pairs. | {"version":"v2","build":"16","env":"production"} |
+| create_time | False | Auxiliary | Epoch timestamp in second of the created time. If missing, this field will be populated automatically. | 1602883670 |
Review comment:
Yes. I missed this.
--
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
[GitHub] [apisix] moonming commented on a change in pull request #6565: docs: update the API docs
Posted by GitBox <gi...@apache.org>.
moonming commented on a change in pull request #6565:
URL: https://github.com/apache/apisix/pull/6565#discussion_r824411588
##########
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:
The ending `list` is redundant?
--
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