test/apisix
1
0
Fork 0
mirror of https://gitee.com/iresty/apisix.git synced 2024-12-03 12:37:36 +08:00
Code Issues Actions Packages Projects Releases Wiki Activity

docs: update the API docs (#6565)

Browse Source
This commit is contained in:
Navendu Pottekkat 2022-03-14 09:24:56 +05:30 committed by GitHub
parent 0f2f807197
commit a490e0a257
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
2 changed files with 327 additions and 341 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

571
docs/en/latest/admin-api.md
View File

@ -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. |
| 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 a random id. |
| DELETE | /apisix/admin/routes/{id} | NULL | Removes the Route with the specified id. |
| PATCH | /apisix/admin/routes/{id} | {...} | Updates the selected attributes of the specified, existing Route. To delete an attribute, set value of attribute set to null. |
| PATCH | /apisix/admin/routes/{id}/{path} | {...} | Updates the attribute specified in the path. The values of other attributes remain unchanged. |
### URI Request Parameters
| parameter | Required | Type | Description | Example |
| --------- | -------- | --------- | ---------------------------- | ------- |
| ttl | False | Auxiliary | Expires after target seconds | ttl=1 |
| parameter | Required | Type | Description | Example |
| --------- | -------- | --------- | --------------------------------------------------- | ------- |
| ttl | False | Auxiliary | Request expires after the specified target seconds. | ttl=1 |
### Request Body Parameters
| Parameter | Required | Type | Description | Example |
| ---------------- | ---------------------------------------- | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------- |
| name | False | Auxiliary | Identifies route names. | route-xxxx |
| desc | False | Auxiliary | route description, usage scenarios, and more. | route xxxx |
| uri | True, can't be used with `uris` | Match Rules | In addition to full matching such as `/foo/bar`、`/foo/gloo`, using different [Router](architecture-design/router.md) allows more advanced matching, see [Router](architecture-design/router.md) for more. | "/hello" |
| uris | True, can't be used with `uri` | Match Rules | The `uri` in the form of a non-empty list means that multiple different uris are allowed, and match any one of them. | ["/hello", "/word"] |
| host | False, can't be used with `hosts` | Match Rules | Currently requesting a domain name, such as `foo.com`; PAN domain names such as `*.foo.com` are also supported. | "foo.com" |
| hosts | False, can't be used with `host` | Match Rules | The `host` in the form of a non-empty list means that multiple different hosts are allowed, and match any one of them. | ["foo.com", "*.bar.com"] |
| remote_addr | False, can't be used with `remote_addrs` | Match Rules | The client requests an IP address: `192.168.1.101`, `192.168.1.102`, and CIDR format support `192.168.1.0/24`. In particular, APISIX also fully supports IPv6 address matching: `::1`, `fe80::1`, `fe80::1/64`, etc. | "192.168.1.0/24" |
| remote_addrs | False, can't be used with `remote_addr` | Match Rules | The `remote_addr` in the form of a non-empty list indicates that multiple different IP addresses are allowed, and match any one of them. | ["127.0.0.1", "192.0.0.0/8", "::1"] |
| methods | False | Match Rules | If empty or without this option, there are no `method` restrictions, and it can be a combination of one or more: `GET`,`POST`,`PUT`,`DELETE`,`PATCH`, `HEAD`,`OPTIONS`,`CONNECT`,`TRACE`. | ["GET", "POST"] |
| priority | False | Match Rules | If different routes contain the same `uri`, determine which route is matched first based on the attribute `priority`. Larger value means higher priority. The default value is 0. | priority = 10 |
| vars | False | Match Rules | A list of one or more `[var, operator, val]` elements, like this: `[[var, operator, val], [var, operator, val], ...]]`. For example: `["arg_name", "==", "json"]` means that the current request parameter `name` is `json`. The `var` here is consistent with the internal variable name of Nginx, so you can also use `request_uri`, `host`, etc. For more details, see [lua-resty-expr](https://github.com/api7/lua-resty-expr) | [["arg_name", "==", "json"], ["arg_age", ">", 18]] |
| filter_func | False | Match Rules | User-defined filtering function. You can use it to achieve matching requirements for special scenarios. This function accepts an input parameter named `vars` by default, which you can use to get Nginx variables. | function(vars) return vars["arg_name"] == "json" end |
| plugins | False | Plugin | See [Plugin](architecture-design/plugin.md) for more | |
| script | False | Script | See [Script](architecture-design/script.md) for more | |
| upstream | False | Upstream | Enabled Upstream configuration, see [Upstream](architecture-design/upstream.md) for more | |
| upstream_id | False | Upstream | Enabled upstream id, see [Upstream](architecture-design/upstream.md) for more | |
| service_id | False | Service | Bound Service configuration, see [Service](architecture-design/service.md) for more | |
| plugin_config_id | False, can't be used with `script` | Plugin | Bound plugin config object, see [Plugin Config](architecture-design/plugin-config.md) for more | |
| labels | False | Match Rules | Key/value pairs to specify attributes | {"version":"v2","build":"16","env":"production"} |
| timeout | False | Auxiliary | Set the upstream timeout for connecting, sending and receiving messages of the route. This option will overwrite the [timeout](#upstream) option which set in upstream configuration. | {"connect": 3, "send": 3, "read": 3} |
| enable_websocket | False | Auxiliary | enable `websocket`(boolean), default `false`. | |
| status | False | Auxiliary | enable this route, default `1`. | `1` to enable, `0` to disable |
| 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 |
| ---------------- | ---------------------------------------- | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------- |
| name | False | Auxiliary | Identifier for the Route. | route-xxxx |
| desc | False | Auxiliary | Description of usage scenarios. | route xxxx |
| uri | True, can't be used with `uris` | Match Rules | Matches the uri. For more advanced matching see [Router](./architecture-design/router.md). | "/hello" |
| uris | True, can't be used with `uri` | Match Rules | Matches with any one of the multiple `uri`s specified in the form of a non-empty list. | ["/hello", "/word"] |
| host | False, can't be used with `hosts` | Match Rules | Matches with domain names such as `foo.com` or PAN domain names like `*.foo.com`. | "foo.com" |
| hosts | False, can't be used with `host` | Match Rules | Matches with any one of the multiple `host`s specified in the form of a non-empty list. | ["foo.com", "*.bar.com"] |
| remote_addr | False, can't be used with `remote_addrs` | Match Rules | Matches with the specified IP address in standard IPv4 format (`192.168.1.101`), CIDR format (`192.168.1.0/24`), or in IPv6 format (`::1`, `fe80::1`, `fe80::1/64`). | "192.168.1.0/24" |
| remote_addrs | False, can't be used with `remote_addr` | Match Rules | Matches with any one of the multiple `remote_addr`s specified in the form of a non-empty list. | ["127.0.0.1", "192.0.0.0/8", "::1"] |
| methods | False | Match Rules | Matches with the specified methods. Matches all methods if empty or unspecified. | ["GET", "POST"] |
| priority | False | Match Rules | If different Routes matches to the same `uri`, then the Route is matched based on its `priority`. A higher value corresponds to higher priority. It is set to `0` by default. | priority = 10 |
| vars | False | Match Rules | Matches based on the specified variables consistent with variables in Nginx. Takes the form `[[var, operator, val], [var, operator, val], ...]]`. Note that this is case sensitive when matching a cookie name. See [lua-resty-expr](https://github.com/api7/lua-resty-expr) for more details. | [["arg_name", "==", "json"], ["arg_age", ">", 18]] |
| filter_func | False | Match Rules | Matches based on a user-defined filtering function. Used in scenarios requiring complex matching. These functions can accept an input parameter `vars` which can be used to access the Nginx variables. | function(vars) return vars["arg_name"] == "json" end |
| plugins | False | Plugin | Plugins that are executed during the request/response cycle. See [Plugin](architecture-design/plugin.md) for more. | |
| script | False | Script | Used for writing arbitrary Lua code or directly calling existing plugins to be executed. See [Script](architecture-design/script.md) for more. | |
| upstream | False | Upstream | Configuration of the [Upstream](./architecture-design/upstream.md). | |
| upstream_id | False | Upstream | Id of the [Upstream](architecture-design/upstream.md) service. | |
| service_id | False | Service | Configuration of the bound [Service](architecture-design/service.md). | |
| plugin_config_id | False, can't be used with `script` | Plugin | [Plugin config](architecture-design/plugin-config.md) bound to the Route. | |
| labels | False | Match Rules | Attributes of the Route specified as key-value pairs. | {"version":"v2","build":"16","env":"production"} |
| timeout | False | Auxiliary | Sets the timeout for connecting to, and sending and receiving messages between the Upstream and the Route. This will overwrite the `timeout` value configured in your [Upstream](#upstream). | {"connect": 3, "send": 3, "read": 3} |
| enable_websocket | False | Auxiliary | Enables a websocket. Set to `false` by default. | |
| status | False | Auxiliary | Enables the current Route. Set to `1` (enabled) by default. | `1` to enable, `0` to disable |
| create_time | False | Auxiliary | Epoch timestamp (in seconds) of the created time. If missing, this field will be populated automatically. | 1602883670 |
| update_time | False | Auxiliary | Epoch timestamp (in seconds) of the updated time. If missing, this field will be populated automatically. | 1602883670 |
There are two points that need special attention:
- For the same type of parameters, such as `host` and `hosts`, `remote_addr` and `remote_addrs` cannot exist at the same time, only one of them can be selected. If enabled at the same time, the API will respond with an error.
- In `vars`, when getting the cookie value, the cookie name is **case-sensitive**. For example: `var` equals "cookie_x_foo" and `var` equals "cookie_X_Foo" means different `cookie`.
Config Example:
Example configuration:
```shell
{
@ -114,7 +107,7 @@ Config Example:
}
```
Example：
Example API usage:
```shell
# Create a route
@ -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}
*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.
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.
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 a random id. |
| DELETE | /apisix/admin/services/{id} | NULL | Removes the Service with the specified id. |
| PATCH | /apisix/admin/services/{id} | {...} | Updates the selected attributes of the specified, existing Service. To delete an attribute, set value of attribute set to null. |
| PATCH | /apisix/admin/services/{id}/{path} | {...} | Updates the attribute specified in the path. The values of other attributes remain unchanged. |
### Request Body Parameters
| Parameter | Required | Type | Description | Example |
| ---------------- | -------- | ----------- | ---------------------------------------------------------------------------------------- | ------------------------------------------------ |
| plugins | False | Plugin | See [Plugin](architecture-design/plugin.md) for more | |
| upstream | False | Upstream | Enabled Upstream configuration, see [Upstream](architecture-design/upstream.md) for more | |
| upstream_id | False | Upstream | Enabled upstream id, see [Upstream](architecture-design/upstream.md) for more | |
| name | False | Auxiliary | Identifies service names. | service-xxxx |
| desc | False | Auxiliary | service usage scenarios, and more. | service xxxx |
| labels | False | Match Rules | Key/value pairs to specify attributes | {"version":"v2","build":"16","env":"production"} |
| enable_websocket | False | Auxiliary | enable `websocket`(boolean), default `false`. | |
| hosts | False | Match Rules | The `host` in the form of a non-empty list means that multiple different hosts are allowed, and match any one of them.| ["foo.com", "*.bar.com"] |
| 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 |
| ---------------- | -------- | ----------- | ------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------ |
| plugins | False | Plugin | Plugins that are executed during the request/response cycle. See [Plugin](architecture-design/plugin.md) for more. | |
| upstream | False | Upstream | Configuration of the [Upstream](./architecture-design/upstream.md). | |
| upstream_id | False | Upstream | Id of the [Upstream](architecture-design/upstream.md) service. | |
| name | False | Auxiliary | Identifier for the Service. | service-xxxx |
| desc | False | Auxiliary | Description of usage scenarios. | service xxxx |
| labels | False | Match Rules | Attributes of the Service specified as key-value pairs. | {"version":"v2","build":"16","env":"production"} |
| enable_websocket | False | Auxiliary | Enables a websocket. Set to `false` by default. | |
| hosts | False | Match Rules | Matches with any one of the multiple `host`s specified in the form of a non-empty list. | ["foo.com", "*.bar.com"] |
| create_time | False | Auxiliary | Epoch timestamp (in seconds) of the created time. If missing, this field will be populated automatically. | 1602883670 |
| update_time | False | Auxiliary | Epoch timestamp (in seconds) of the updated time. If missing, this field will be populated automatically. | 1602883670 |
Config Example:
Example configuration:
```shell
{
@ -328,7 +323,7 @@ Config Example:
}
```
Example：
Example API usage:
```shell
$ curl http://127.0.0.1:9080/apisix/admin/services/201 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -i -d '
@ -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 seconds) of the created time. If missing, this field will be populated automatically. | 1602883670 |
| update_time | False | Auxiliary | Epoch timestamp (in seconds) of the updated time. If missing, this field will be populated automatically. | 1602883670 |
Config Example:
Example Configuration:
```shell
{
@ -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 a Route or Service, the Authentication Plugin infers the Consumer from the request and does not require any parameters. Whereas, when it is bound to a Consumer, username, password and other information needs to be provided.
Example:
Example API usage:
```shell
$ curl http://127.0.0.1:9080/apisix/admin/consumers -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -i -d '
@ -498,86 +493,86 @@ Since `v2.2`, we can bind multiple authentication plugins to the same consumer.
### Response Parameters
Return response from etcd currently.
Currently, the response is returned from etcd.
[Back to TOC](#table-of-contents)
## Upstream
*API*：/apisix/admin/upstreams/{id}
**API**: /apisix/admin/upstreams/{id}
*Description*：Upstream configuration can be directly bound to the specified `Route` or it can be bound to `Service`, but the configuration in `Route` has a higher priority. The priority behavior here is very similar to `Plugin`.
Upstream is a virtual host abstraction that performs load balancing on a given set of service nodes according to the configured rules.
An Upstream configuration can be directly bound to a Route or a Service, but the configuration in Route has a higher priority. This behavior is consistent with priority followed by the Plugin object.
### Request Methods
| Method | Request URI | Request Body | Description |
| ------ | ----------------------------------- | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| GET | /apisix/admin/upstreams | NULL | Fetch resource list |
| GET | /apisix/admin/upstreams/{id} | NULL | Fetch resource |
| PUT | /apisix/admin/upstreams/{id} | {...} | Create resource by ID |
| POST | /apisix/admin/upstreams | {...} | Create resource, and ID is generated by server |
| DELETE | /apisix/admin/upstreams/{id} | NULL | Remove resource |
| PATCH | /apisix/admin/upstreams/{id} | {...} | Standard PATCH. Update some attributes of the existing Upstream, 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/upstreams/{id}/{path} | {...} | SubPath PATCH, specify the attribute of Upstream 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 example |
| Method | Request URI | Request Body | Description |
| ------ | ----------------------------------- | ------------ | -------------------------------------------------------------------------------------------------------------------------------- |
| GET | /apisix/admin/upstreams | NULL | Fetch a list of all configured Upstreams. |
| GET | /apisix/admin/upstreams/{id} | NULL | Fetches specified Upstream by id. |
| PUT | /apisix/admin/upstreams/{id} | {...} | Creates an Upstream with the specified id. |
| POST | /apisix/admin/upstreams | {...} | Creates an Upstream and assigns a random id. |
| DELETE | /apisix/admin/upstreams/{id} | NULL | Removes the Upstream with the specified id. |
| PATCH | /apisix/admin/upstreams/{id} | {...} | Updates the selected attributes of the specified, existing Upstream. To delete an attribute, set value of attribute set to null. |
| PATCH | /apisix/admin/upstreams/{id}/{path} | {...} | Updates the attribute specified in the path. The values of other attributes remain unchanged. |
### Request Body Parameters
In addition to the basic complex equalization algorithm selection, APISIX's Upstream also supports logic for upstream passive health check and retry, see the table below.
In addition to the equalization algorithm selections, Upstream also supports passive health check and retry for the upstream. See the table below for more details:
|Name |Optional|Description|Example|
|----------------|--------|-----------|-----------|
|type |required|the balancer algorithm||
|nodes |required, can't be used with `service_name` |Hash table or array. If it is a hash table, the key of the internal element is the upstream machine address list, the format is `Address + (optional) Port`, where the address part can be IP or domain name, such as `192.168.1.100:80`, `foo.com:80`, etc. The value is the weight of node. If it is an array, each item is a hash table with key `host`/`weight` and optional `port`/`priority`. The `nodes` can be empty, which means it is a placeholder and will be filled later. Clients use such an upstream will get 502 response. |`192.168.1.100:80`|
|service_name |required, can't be used with `nodes` |the name of service used in the service discovery, see [discovery](discovery.md) for more details|`a-bootiful-client`|
|discovery_type |required, if `service_name` is used | the type of service discovery, see [discovery](discovery.md) for more details|`eureka`|
|hash_on |optional|This option is only valid if the `type` is `chash`. Supported types `vars`(Nginx variables), `header`(custom header), `cookie`, `consumer`, the default value is `vars`.||
|key |optional|This option is only valid if the `type` is `chash`. Find the corresponding node `id` according to `hash_on` and `key`. When `hash_on` is set as `vars`, `key` is the required parameter, for now, it support nginx built-in variables like `uri, server_name, server_addr, request_uri, remote_port, remote_addr, query_string, host, hostname, arg_***`, `arg_***` is arguments in the request line, [Nginx variables list](http://nginx.org/en/docs/varindex.html). When `hash_on` is set as `header`, `key` is the required parameter, and `header name` is customized. When `hash_on` is set to `cookie`, `key` is the required parameter, and `cookie name` is customized. When `hash_on` is set to `consumer`, `key` does not need to be set. In this case, the `key` adopted by the hash algorithm is the `consumer_name` authenticated. If the specified `hash_on` and `key` can not fetch values, it will be fetch `remote_addr` by default.||
|checks |optional|Configure the parameters of the health check. For details, refer to [health-check](health-check.md).||
|retries |optional|Pass the request to the next upstream using the underlying Nginx retry mechanism, the retry mechanism is enabled by default and set the number of retries according to the number of available backend nodes. If `retries` option is explicitly set, it will override the default value. `0` means disable retry mechanism.||
|retry_timeout |optional|Configure a number to limit the amount of seconds that retries can be continued, and do not continue retries if the previous request and retry requests have taken too long. `0` means disable retry timeout mechanism.||
|timeout |optional| Set the timeout for connecting, sending and receiving messages. ||
|name |optional|Identifies upstream names||
|desc |optional|upstream usage scenarios, and more.||
|pass_host |optional| `host` option when the request is sent to the upstream, can be one of [`pass`, `node`, `rewrite`], the default option is `pass`. `pass`: Pass the client's host transparently to the upstream; `node`: Use the host configured in the node of `upstream`; `rewrite`: Use the value of the configuration `upstream_host`.||
|upstream_host |optional|Specify the host of the upstream request. This option is only valid if the `pass_host` is `rewrite`.||
|scheme |optional |The scheme used when talk with the upstream. For L7 proxy, the value is one of ['http', 'https', 'grpc', 'grpcs']. For L4 proxy, the value is one of ['tcp', 'udp', 'tls']. Default to 'http'. See below for more details.||
|labels |optional |Key/value pairs to specify attributes|{"version":"v2","build":"16","env":"production"}|
|create_time |optional| epoch timestamp in second, like `1602883670`, will be created automatically if missing|1602883670|
|update_time |optional| epoch timestamp in second, like `1602883670`, will be created automatically if missing|1602883670|
|tls.client_cert |optional| Set the client certificate when connecting to TLS upstream, see below for more details||
|tls.client_key |optional| Set the client private key when connecting to TLS upstream, see below for more details||
|keepalive_pool.size |optional| Set `keepalive` directive dynamically, see below for more details||
|keepalive_pool.idle_timeout |optional| Set `keepalive_timeout` directive dynamically, see below for more details||
|keepalive_pool.requests |optional| Set `keepalive_requests` directive dynamically, see below for more details||
| Name | Optional | Description | Example |
| --------------------------- | ------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| type | required | Load balancing algorithm to be used. | |
| nodes | required, can't be used with `service_name` | IP addresses (with optional ports) of the Upstream nodes represented as a hash table or an array. In the hash table, the key is the IP address and the value is the weight of the node for the load balancing algorithm. In the array, each item is a hash table with keys `host`, `weight`, and the optional `port` and `priority`. Empty nodes are treated as placeholders and clients trying to access this Upstream will receive a 502 response. | `192.168.1.100:80` |
| service_name | required, can't be used with `nodes` | Service name used for [service discovery](discovery.md). | `a-bootiful-client` |
| discovery_type | required, if `service_name` is used | The type of service [discovery](discovery.md). | `eureka` |
| hash_on | optional | Only valid if the `type` is `chash`. Supports Nginx variables (`vars`), custom headers (`header`), `cookie` and `consumer`. Defaults to `vars`. | |
| key | optional | Only valid if the `type` is `chash`. Finds the corresponding node `id` according to `hash_on` and `key` values. When `hash_on` is set to `vars`, `key` is a required parameter and it supports [Nginx variables](http://nginx.org/en/docs/varindex.html). When `hash_on` is set as `header`, `key` is a required parameter, and `header name` can be customized. When `hash_on` is set to `cookie`, `key` is also a required parameter, and `cookie name` can be customized. When `hash_on` is set to `consumer`, `key` need not be set and the `key` used by the hash algorithm would be the authenticated `consumer_name`. If the specified `hash_on` and `key` fail to fetch the values, it will default to `remote_address`. | `uri`, `server_name`, `server_addr`, `request_uri`, `remote_port`, `remote_addr`, `query_string`, `host`, `hostname`, `arg_***`, `arg_***` |
| checks | optional | Configures the parameters for the [health check](health-check.md). | |
| retries | optional | Sets the number of retries while passing the request to Upstream using the underlying Nginx mechanism. Set according to the number of available backend nodes by default. Setting this to `0` disables retry. | |
| retry_timeout | optional | Timeout to continue with retries. Setting this to `0` disables the retry timeout. | |
| timeout | optional | Sets the timeout for connecting to, and sending and receiving messages to and from the Upstream. | |
| name | optional | Identifier for the Upstream. | |
| desc | optional | Description of usage scenarios. | |
| pass_host | optional | Configures the `host` when the request is forwarded to the upstream. Can be one of `pass`, `node` or `rewrite`. Defaults to `pass` if not specified. `pass`- transparently passes the client's host to the Upstream. `node`- uses the host configured in the node of the Upstream. `rewrite`- Uses the value configured in `upstream_host`. | |
| upstream_host | optional | Specifies the host of the Upstream request. This is only valid if the `pass_host` is set to `rewrite`. | |
| scheme | optional | The scheme used when communicating with the Upstream. For an L7 proxy, this value can be one of 'http', 'https', 'grpc', 'grpcs'. For an L4 proxy, this value could be one of 'tcp', 'udp', 'tls'. Defaults to 'http'. | |
| labels | optional | Attributes of the Upstream specified as key-value pairs. | {"version":"v2","build":"16","env":"production"} |
| create_time | optional | Epoch timestamp (in seconds) of the created time. If missing, this field will be populated automatically. | 1602883670 |
| update_time | optional | Epoch timestamp (in seconds) of the updated time. If missing, this field will be populated automatically. | 1602883670 |
| tls.client_cert | optional | Sets the client certificate while connecting to a TLS Upstream. | |
| tls.client_key | optional | Sets the client private key while connecting to a TLS Upstream. | |
| keepalive_pool.size | optional | Sets `keepalive` directive dynamically. | |
| keepalive_pool.idle_timeout | optional | Sets `keepalive_timeout` directive dynamically. | |
| keepalive_pool.requests | optional | Sets `keepalive_requests` directive dynamically. | |
`type` can be one of:
An Upstream can be one of the following `types`:
* `roundrobin`: roundrobin with weight
* `chash`: consistent hash
* `ewma`: pick one of node which has minimum latency. See https://en.wikipedia.org/wiki/EWMA_chart for details.
* `least_conn`: pick node which has the lowest `(active_conn + 1) / weight`. Note the `active connection` concept is the same with Nginx: it is a connection in used by a request.
* user-defined balancer which can be loaded via `require("apisix.balancer.your_balancer")`.
- `roundrobin`: Round robin balancing with weights.
- `chash`: Consistent hash.
- `ewma`: Pick the node with minimum latency. See [EWMA Chart](https://en.wikipedia.org/wiki/EWMA_chart) for more details.
- `least_conn`: Picks the node with the lowest value of `(active_conn + 1) / weight`. Here, an active connection is a connection being used by the request and is similar to the concept in Nginx.
- user-defined load balancer loaded via `require("apisix.balancer.your_balancer")`.
`hash_on` can be set to different types:
The following should be considered when setting the `hash_on` value:
1. When it is `vars`, the `key` is required. The `key` can be any [Nginx builtin variables](http://nginx.org/en/docs/varindex.html), without the prefix '$'.
1. When it is `header`, the `key` is required. It is equal to "http_`key`".
1. When it is `cookie`, the `key` is required. It is equal to "cookie_`key`". Please note that the cookie name is **case-sensitive**. For example: "cookie_x_foo" and "cookie_X_Foo" indicate different `cookie`.
1. When it is `consumer`, the `key` is optional. The key is the `consumer_name` set by authentication plugin.
1. When it is `vars_combinations`, the `key` is required. The `key` can be any [Nginx builtin variables](http://nginx.org/en/docs/varindex.html) combinations, such as `$request_uri$remote_addr`.
1. If there is no value for either `hash_on` or `key`, `remote_addr` will be used as key.
- When set to `vars`, a `key` is required. The value of the key can be any of the [Nginx variables](http://nginx.org/en/docs/varindex.html) without the `$` prefix.
- When set to `header`, a `key` is required. This is equal to "http\_`key`".
- When set to `cookie`, a `key` is required. This key is equal to "cookie\_`key`". The cookie name is case-sensitive.
- When set to `consumer`, the `key` is optional and the key is set to the `consumer_name` captured from the authentication Plugin.
- When set to `vars_combinations`, the `key` is required. The value of the key can be a combination of any of the [Nginx variables](http://nginx.org/en/docs/varindex.html) like `$request_uri$remote_addr`.
- When no value is set for either `hash_on` or `key`, the key defaults to `remote_addr`.
Features below require APISIX to run on [APISIX-OpenResty](./how-to-build.md#step-6-build-openresty-for-apache-apisix):
The features described below requires APISIX to be run on [APISIX-OpenResty](./how-to-build.md#step-6-build-openresty-for-apache-apisix):
The `scheme` can be set to `tls`, which actually means "TLS over TCP".
You can set the `scheme` to `tls`, which means "TLS over TCP".
`tls.client_cert/key` can be used to communicate with upstream via mTLS.
Their formats are the same as SSL's `cert` and `key` fields.
To use mTLS to communicate with Upstream, you can use the `tls.client_cert/key` in the same format as SSL's `cert` and `key` fields.
`keepalive_pool` allows the upstream to have its separate connection pool.
Its children fields, like `requests`, can be used to configure the upstream keepalive options.
To allow Upstream to have a separate connection pool, use `keepalive_pool`. It can be configured by modifying its child fields.
**Config Example:**
Example Configuration:
```shell
{
@ -600,9 +595,9 @@ Its children fields, like `requests`, can be used to configure the upstream keep
}
```
**Example:**
Example API usage:
Example 1: Create an upstream and modify the data of `nodes`
Example 1: Create an Upstream and modify the data in `nodes`
```shell
# Create upstream
@ -682,7 +677,7 @@ After the execution is successful, nodes will not retain the original data, and
```
Example 2: How to proxy client request to `https` upstream service
Example 2: Proxy client request to `https` Upstream service
1. Create a route and configure the upstream scheme as `https`.
@ -700,9 +695,9 @@ $ curl -i http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f0343
}'
```
After the execution is successful, the scheme when requesting to communicate with the upstream will be `https`.
After successful execution, the scheme when requesting to communicate with the upstream will be `https`.
2. Send a request for testing.
2. Send a request to test.
```shell
$ curl http://127.0.0.1:9080/get
@ -720,85 +715,83 @@ $ curl http://127.0.0.1:9080/get
}
```
The request is successful, which means that the proxy upstream `https` is valid.
The request is successful, meaning that the proxy Upstream `https` is valid.
**Note:**
**Note**:
Each node can be configured with a priority. A node with low priority will only be
used when all the nodes with higher priority are unavailable or tried.
used when all the nodes with higher priority have been tried or are unavailable.
As the default priority is 0, we can configure nodes with negative priority as the backup.
As the default priority is 0, nodes with negative priority can be configured as a backup.
For example:
```json
{
"uri": "/hello",
"upstream": {
"type": "roundrobin",
"nodes": [
{"host": "127.0.0.1", "port": 1980, "weight": 2000},
{"host": "127.0.0.1", "port": 1981, "weight": 1, "priority": -1}
],
"checks": {
"active": {
"http_path": "/status",
"healthy": {
"interval": 1,
"successes": 1
},
"unhealthy": {
"interval": 1,
"http_failures": 1
}
}
"uri": "/hello",
"upstream": {
"type": "roundrobin",
"nodes": [
{ "host": "127.0.0.1", "port": 1980, "weight": 2000 },
{ "host": "127.0.0.1", "port": 1981, "weight": 1, "priority": -1 }
],
"checks": {
"active": {
"http_path": "/status",
"healthy": {
"interval": 1,
"successes": 1
},
"unhealthy": {
"interval": 1,
"http_failures": 1
}
}
}
}
}
```
Node `127.0.0.2` will be used only after `127.0.0.1` is unavailable or tried.
Therefore, it is the backup of `127.0.0.1`.
Node `127.0.0.2` will be used only after `127.0.0.1` is tried or unavailable.
It can therefore act as a backup for the node `127.0.0.1`.
### Response Parameters
Return response from etcd currently.
Currently, the response is returned from etcd.
[Back to TOC](#table-of-contents)
## SSL
*API*：/apisix/admin/ssl/{id}
*Description*：SSL.
**API**:/apisix/admin/ssl/{id}
### Request Methods
| Method | Request URI | Request Body | Description |
| ------ | ---------------------- | ------------ | ---------------------------------------------- |
| GET | /apisix/admin/ssl | NULL | Fetch resource list |
| GET | /apisix/admin/ssl/{id} | NULL | Fetch resource |
| PUT | /apisix/admin/ssl/{id} | {...} | Create resource by ID |
| POST | /apisix/admin/ssl | {...} | Create resource, and ID is generated by server |
| DELETE | /apisix/admin/ssl/{id} | NULL | Remove resource |
| Method | Request URI | Request Body | Description |
| ------ | ---------------------- | ------------ | ----------------------------------------------- |
| GET | /apisix/admin/ssl | NULL | Fetches a list of all configured SSL resources. |
| GET | /apisix/admin/ssl/{id} | NULL | Fetch specified resource by id. |
| PUT | /apisix/admin/ssl/{id} | {...} | Creates a resource with the specified id. |
| POST | /apisix/admin/ssl | {...} | Creates a resource and assigns a random id. |
| DELETE | /apisix/admin/ssl/{id} | NULL | Removes the resource with the specified id. |
### Request Body Parameters
| Parameter | Required | Type | Description | Example |
| ----------- | -------- | ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------ |
| cert | True | Certificate | https certificate | |
| key | True | Private key | https private key | |
| certs | False | An array of certificate | when you need to configure multiple certificate for the same domain, you can pass extra https certificates (excluding the one given as cert) in this field | |
| keys | False | An array of private key | https private keys. The keys should be paired with certs above | |
| client.ca | False | Certificate| set the CA certificate which will use to verify client. This feature requires OpenResty 1.19+. | |
| client.depth | False | Certificate| set the verification depth in the client certificates chain, default to 1. This feature requires OpenResty 1.19+. | |
| snis | True | Match Rules | a non-empty arrays of https SNI | |
| 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 |
| status | False | Auxiliary | enable this SSL, default `1`. | `1` to enable, `0` to disable |
| Parameter | Required | Type | Description | Example |
| ------------ | -------- | ------------------------ | -------------------------------------------------------------------------------------------------------------- | ------------------------------------------------ |
| cert | True | Certificate | HTTPS certificate. | |
| key | True | Private key | HTTPS private key. | |
| certs | False | An array of certificates | Used for configuring multiple certificates for the same domain excluding the one provided in the `cert` field. | |
| keys | False | An array of private keys | Private keys to pair with the `certs`. | |
| client.ca | False | Certificate | Sets the CA certificate that verifies the client. Requires OpenResty 1.19+. | |
| client.depth | False | Certificate | Sets the verification depth in client certificate chains. Defaults to 1. Requires OpenResty 1.19+. | |
| snis | True | Match Rules | A non-empty array of HTTPS SNI | |
| labels | False | Match Rules | Attributes of the resource specified as key-value pairs. | {"version":"v2","build":"16","env":"production"} |
| create_time | False | Auxiliary | Epoch timestamp (in seconds) of the created time. If missing, this field will be populated automatically. | 1602883670 |
| update_time | False | Auxiliary | Epoch timestamp (in seconds) of the updated time. If missing, this field will be populated automatically. | 1602883670 |
| status | False | Auxiliary | Enables the current SSL. Set to `1` (enabled) by default. | `1` to enable, `0` to disable |
Config Example:
Example Configuration:
```shell
{
@ -809,81 +802,79 @@ Config Example:
}
```
More examples can be found in [Certificate](./certificate.md).
See [Certificate](./certificate.md) for more examples.
## Global Rule
*API*：/apisix/admin/global_rules/{id}
**API**: /apisix/admin/global_rules/{id}
*Description*: Set plugins which run globally. Those plugins will be run before any Route/Service level plugins.
Sets Plugins which run globally. i.e these Plugins will be run before any Route/Service level Plugins.
### Request Methods
| Method | Request URI | Request Body | Description |
| ------ | -------------------------------------- | ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| GET | /apisix/admin/global_rules | NULL | Fetch resource list |
| GET | /apisix/admin/global_rules/{id} | NULL | Fetch resource |
| PUT | /apisix/admin/global_rules/{id} | {...} | Create resource by ID |
| DELETE | /apisix/admin/global_rules/{id} | NULL | Remove resource |
| PATCH | /apisix/admin/global_rules/{id} | {...} | Standard PATCH. Update some attributes of the existing global rule, 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/global_rules/{id}/{path} | {...} | SubPath PATCH, specify the attribute of global rule 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. |
| Method | Request URI | Request Body | Description |
| ------ | -------------------------------------- | ------------ | ----------------------------------------------------------------------------------------------------------------------------------- |
| GET | /apisix/admin/global_rules | NULL | Fetches a list of all Global Rules. |
| GET | /apisix/admin/global_rules/{id} | NULL | Fetches specified Global Rule by id. |
| PUT | /apisix/admin/global_rules/{id} | {...} | Creates a Global Rule with the specified id. |
| DELETE | /apisix/admin/global_rules/{id} | NULL | Removes the Global Rule with the specified id. |
| PATCH | /apisix/admin/global_rules/{id} | {...} | Updates the selected attributes of the specified, existing Global Rule. To delete an attribute, set value of attribute set to null. |
| PATCH | /apisix/admin/global_rules/{id}/{path} | {...} | Updates the attribute specified in the path. The values of other attributes remain unchanged. |
### Request Body Parameters
| Parameter | Required | Description | Example |
| ----------- | -------- | ------------------------------------------------------------------- | ---------- |
| plugins | True | See [Plugin](architecture-design/plugin.md) | |
| create_time | False | epoch timestamp in second, will be created automatically if missing | 1602883670 |
| update_time | False | epoch timestamp in second, will be created automatically if missing | 1602883670 |
| Parameter | Required | Description | Example |
| ----------- | -------- | ------------------------------------------------------------------------------------------------------------------ | ---------- |
| plugins | True | Plugins that are executed during the request/response cycle. See [Plugin](architecture-design/plugin.md) for more. | |
| create_time | False | Epoch timestamp (in seconds) of the created time. If missing, this field will be populated automatically. | 1602883670 |
| update_time | False | Epoch timestamp (in seconds) of the updated time. If missing, this field will be populated automatically. | 1602883670 |
## Plugin config
*API*：/apisix/admin/plugin_configs/{id}
**API**: /apisix/admin/plugin_configs/{id}
*Description*: Provide a group of plugins which can be reused across routes.
Group of Plugins which can be reused across Routes.
### Request Methods
| Method | Request URI | Request Body | Description |
| ------ | ---------------------------------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| GET | /apisix/admin/plugin_configs | NULL | Fetch resource list |
| GET | /apisix/admin/plugin_configs/{id} | NULL | Fetch resource |
| PUT | /apisix/admin/plugin_configs/{id} | {...} | Create resource by ID |
| DELETE | /apisix/admin/plugin_configs/{id} | NULL | Remove resource |
| PATCH | /apisix/admin/plugin_configs/{id} | {...} | Standard PATCH. Update some attributes of the existing plugin config, 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/plugin_configs/{id}/{path} | {...} | SubPath PATCH, specify the attribute of plugin config 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. |
| Method | Request URI | Request Body | Description |
| ------ | ---------------------------------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------- |
| GET | /apisix/admin/plugin_configs | NULL | Fetches a list of all Plugin configs. |
| GET | /apisix/admin/plugin_configs/{id} | NULL | Fetches specified Plugin config by id. |
| PUT | /apisix/admin/plugin_configs/{id} | {...} | Creates a new Plugin config with the specified id. |
| DELETE | /apisix/admin/plugin_configs/{id} | NULL | Removes the Plugin config with the specified id. |
| PATCH | /apisix/admin/plugin_configs/{id} | {...} | Updates the selected attributes of the specified, existing Plugin config. To delete an attribute, set value of attribute set to null. |
| PATCH | /apisix/admin/plugin_configs/{id}/{path} | {...} | Updates the attribute specified in the path. The values of other attributes remain unchanged. |
### Request Body Parameters
| Parameter | Required | Description | Example |
| ----------- | -------- | ------------------------------------------------------------------- | ------------------------------------------------ |
| plugins | True | See [Plugin](architecture-design/plugin.md) | |
| desc | False | description, usage scenarios, and more. | customer xxxx |
| labels | False | Key/value pairs to specify attributes | {"version":"v2","build":"16","env":"production"} |
| create_time | False | epoch timestamp in second, will be created automatically if missing | 1602883670 |
| update_time | False | epoch timestamp in second, will be created automatically if missing | 1602883670 |
| Parameter | Required | Description | Example |
| ----------- | -------- | ------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------ |
| plugins | True | Plugins that are executed during the request/response cycle. See [Plugin](architecture-design/plugin.md) for more. | |
| desc | False | Description of usage scenarios. | customer xxxx |
| labels | False | Attributes of the Plugin config specified as key-value pairs. | {"version":"v2","build":"16","env":"production"} |
| create_time | False | Epoch timestamp (in seconds) of the created time. If missing, this field will be populated automatically. | 1602883670 |
| update_time | False | Epoch timestamp (in seconds) of the updated time. If missing, this field will be populated automatically. | 1602883670 |
[Back to TOC](#table-of-contents)
## Plugin Metadata
*API*：/apisix/admin/plugin_metadata/{plugin_name}
*Description*: plugin metadata.
**API**: /apisix/admin/plugin_metadata/{plugin_name}
### Request Methods
| Method | Request URI | Request Body | Description |
| ------ | ------------------------------------------- | ------------ | ------------------------------ |
| GET | /apisix/admin/plugin_metadata/{plugin_name} | NULL | Fetch resource |
| PUT | /apisix/admin/plugin_metadata/{plugin_name} | {...} | Create resource by plugin name |
| DELETE | /apisix/admin/plugin_metadata/{plugin_name} | NULL | Remove resource |
| Method | Request URI | Request Body | Description |
| ------ | ------------------------------------------- | ------------ | --------------------------------------------------------------- |
| GET | /apisix/admin/plugin_metadata/{plugin_name} | NULL | Fetches the metadata of the specified Plugin by `plugin_name`. |
| PUT | /apisix/admin/plugin_metadata/{plugin_name} | {...} | Creates metadata for the Plugin specified by the `plugin_name`. |
| DELETE | /apisix/admin/plugin_metadata/{plugin_name} | NULL | Removes metadata for the Plugin specified by the `plugin_name`. |
### Request Body Parameters
A json object with a data structure defined according to `metadata_schema` of the plugin ({plugin_name}).
A JSON object defined according to the `metadata_schema` of the Plugin ({plugin_name}).
Config Example:
Example Configuration:
```shell
$ curl http://127.0.0.1:9080/apisix/admin/plugin_metadata/example-plugin -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -i -X PUT -d '
@ -900,22 +891,20 @@ Content-Type: text/plain
## Plugin
*API*：/apisix/admin/plugins/{plugin_name}
*Description*: plugin
**API**: /apisix/admin/plugins/{plugin_name}
### Request Methods
| Method | Request URI | Request Body | Description |
| ------ | ----------------------------------- | ------------ | ------------------- |
| GET | /apisix/admin/plugins/list | NULL | Fetch resource list |
| GET | /apisix/admin/plugins/{plugin_name} | NULL | Fetch resource |
| Method | Request URI | Request Body | Description |
| ------ | ----------------------------------- | ------------ | ---------------------------------------------- |
| GET | /apisix/admin/plugins/list | NULL | Fetches a list of all Plugins. |
| GET | /apisix/admin/plugins/{plugin_name} | NULL | Fetches the specified Plugin by `plugin_name`. |
### Request Body Parameters
Get the plugin ({plugin_name}) of the data structure.
The Plugin ({plugin_name}) of the data structure.
Example：
Example API usage:
```shell
$ curl "http://127.0.0.1:9080/apisix/admin/plugins/list" -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1'
@ -925,53 +914,53 @@ $ curl "http://127.0.0.1:9080/apisix/admin/plugins/key-auth" -H 'X-API-KEY:
{"properties":{"disable":{"type":"boolean"}},"additionalProperties":false,"type":"object"}
```
*API*：/apisix/admin/plugins?all=true
**API**: /apisix/admin/plugins?all=true
*Description*: all the attributes of all plugins, each plugin includes `name`, `priority`, `type`, `schema`, `consumer_schema` and `version`.
Get all attributes from all Plugins. Each Plugin has the attributes `name`, `priority`, `type`, `schema`, `consumer_schema` and `version`. Defaults to only HTTP Plugins.
By default, this API only returns the http plugins. If you need stream plugins, use `/apisix/admin/plugins?all=true&subsystem=stream`.
If you need to get attributes from stream Plugins, use `/apisix/admin/plugins?all=true&subsystem=stream`.
### Request Methods
| Method | Request URI | Request Body | Description |
| ------ | ------------------------------ | ------------ | -------------- |
| GET | /apisix/admin/plugins?all=true | NULL | Fetch resource |
| Method | Request URI | Request Body | Description |
| ------ | ------------------------------ | ------------ | ---------------------------------------- |
| GET | /apisix/admin/plugins?all=true | NULL | Fetches all attributes from all Plugins. |
### Request Arguments
| Name | Description | Default |
| --------- | ------------------------------ | ------------ |
| subsystem | the subsystem of plugins | http |
| Name | Description | Default |
| --------- | ----------------------------- | ------- |
| subsystem | The subsystem of the Plugins. | http |
[Back to TOC](#table-of-contents)
## Stream Route
*API*：/apisix/admin/stream_routes/{id}
**API**: /apisix/admin/stream_routes/{id}
*Description*：Stream Route is the route used in the stream proxy. See [Stream Proxy](./stream-proxy.md) for the details.
Route used in the [Stream Proxy](./stream-proxy.md).
### Request Methods
| Method | Request URI | Request Body | Description |
| ------ | -------------------------------- | ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| GET | /apisix/admin/stream_routes | NULL | Fetch resource list |
| GET | /apisix/admin/stream_routes/{id} | NULL | Fetch resource |
| PUT | /apisix/admin/stream_routes/{id} | {...} | Create resource by ID |
| POST | /apisix/admin/stream_routes | {...} | Create resource, and ID is generated by server |
| DELETE | /apisix/admin/stream_routes/{id} | NULL | Remove resource |
| Method | Request URI | Request Body | Description |
| ------ | -------------------------------- | ------------ | ----------------------------------------------- |
| GET | /apisix/admin/stream_routes | NULL | Fetches a list of all configured Stream Routes. |
| GET | /apisix/admin/stream_routes/{id} | NULL | Fetches specified Stream Route by id. |
| PUT | /apisix/admin/stream_routes/{id} | {...} | Creates a Stream Route with the specified id. |
| POST | /apisix/admin/stream_routes | {...} | Creates a Stream Route and assigns a random id. |
| DELETE | /apisix/admin/stream_routes/{id} | NULL | Removes the Stream Route with the specified id. |
### Request Body Parameters
| Parameter | Required | Type | Description | Example |
| ---------------- | ------| -------- | ------| -----|
| upstream | False | Upstream | Upstream configuration, see [Upstream](architecture-design/upstream.md) for more details | |
| upstream_id | False | Upstream | specify the upstream id, see [Upstream](architecture-design/upstream.md) for more details | |
| remote_addr | False | IP/CIDR | Filter option: forward to upstream if client IP matches | "127.0.0.1/32" or "127.0.0.1" |
| server_addr | False | IP/CIDR | Filter option: forward to upstream if APISIX server IP matches with server_addr | "127.0.0.1/32" or "127.0.0.1" |
| server_port | False | Integer | Filter option: forward to upstream if APISIX server port matches with server_port | 9090 |
| sni | False | Host | server name indication | "test.com" |
| Parameter | Required | Type | Description | Example |
| ----------- | -------- | -------- | ------------------------------------------------------------------- | ----------------------------- |
| upstream | False | Upstream | Configuration of the [Upstream](./architecture-design/upstream.md). | |
| upstream_id | False | Upstream | Id of the [Upstream](architecture-design/upstream.md) service. | |
| remote_addr | False | IP/CIDR | Filters Upstream forwards by matching with client IP. | "127.0.0.1/32" or "127.0.0.1" |
| server_addr | False | IP/CIDR | Filters Upstream forwards by matching with APISIX Server IP. | "127.0.0.1/32" or "127.0.0.1" |
| server_port | False | Integer | Filters Upstream forwards by matching with APISIX Server port. | 9090 |
| sni | False | Host | Server Name Indication. | "test.com" |
To know more about how the filter works, see the documentation [here](./stream-proxy.md#more-route-match-options)
To learn more about filtering in stream proxies, check [this](./stream-proxy.md#more-route-match-options) document.
[Back to TOC](#table-of-contents)

97
docs/en/latest/control-api.md
View File

@ -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
* Expose the internal state of APISIX.
* Control the behavior of a single, isolated APISIX data plane.
By default, the control API server is enabled and listens to `127.0.0.1:9090`. You can change it via
the `control` section under `apisix` in `conf/config.yaml`:
To change the default endpoint (`127.0.0.1:9090`) of the Control API server, change the `ip` and `port` in the `control` section in your configuration file (`conf/config.yaml`):
```yaml
apisix:
@ -38,26 +37,25 @@ apisix:
port: 9090
```
The control API server does not support parameter matching by default, if you want to enable parameter matching in plugin's control API
you can add `router: 'radixtree_uri_with_parameter'` to the `control` section.
To enable parameter matching in plugin's control API, add `router: 'radixtree_uri_with_parameter'` to the control section.
Note that the control API server should not be configured to listen to the public traffic!
**Note**: Never configure the control API server to listen to public traffic.
## Control API Added via plugin
## Control API Added via Plugins
Plugin can add its control API when it is enabled.
Some plugins in APISIX have added their own control APIs. If you are interested in these APIs,
please refer to their documentation.
[Plugins](./architecture-design/plugin.md) can be enabled to add its control API.
## Plugin independent Control API
Some Plugins have their own control APIs. See the documentation of the specific Plugin to learn more.
Here is the supported API:
## Plugin Independent Control API
The supported APIs are listed below.
### GET /v1/schema
Introduced since `v2.2`.
Introduced in [v2.2](https://github.com/apache/apisix/releases/tag/2.2).
Return the jsonschema used by this APISIX instance in the format below:
Returns the JSON schema used by the APISIX instance:
```json
{
@ -90,15 +88,13 @@ Return the jsonschema used by this APISIX instance in the format below:
}
```
For `plugins` part, only enabled plugins will be returned. Some plugins may lack
of fields like `consumer_schema` or `type`, it is depended on by the plugin's
definition.
**Note**: Only the enabled `plugins` are returned and they may lack fields like `consumer_schema` or `type` depending on how they were defined.
### GET /v1/healthcheck
Introduced since `v2.3`.
Introduced in [v2.3](https://github.com/apache/apisix/releases/tag/2.3).
Return current [health check](health-check.md) status in the format below:
Returns a [health check](health-check.md) of the APISIX instance.
```json
[
@ -159,16 +155,16 @@ Return current [health check](health-check.md) status in the format below:
]
```
Each entry contains fields below:
Each of the returned objects contain the following fields:
* src_type: where the health checker comes from. The value is one of `["routes", "services", "upstreams"]`.
* src_id: the id of object which creates the health checker. For example, if Upstream
object with id 1 creates a health checker, the `src_type` is `upstreams` and the `src_id` is `1`.
* name: the name of the health checker.
* nodes: the target nodes of the health checker.
* healthy_nodes: the healthy node known by the health checker.
* src_type: where the health checker is reporting from. Value is one of `["routes", "services", "upstreams"]`.
* src_id: id of the object creating the health checker. For example, if an Upstream
object with id `1` creates a health checker, the `src_type` is `upstreams` and the `src_id` is `1`.
* name: name of the health checker.
* nodes: target nodes of the health checker.
* healthy_nodes: healthy nodes discovered by the health checker.
User can also use `/v1/healthcheck/$src_type/$src_id` can get the status of a health checker.
You can also use `/v1/healthcheck/$src_type/$src_id` to get the health status of specific nodes.
For example, `GET /v1/healthcheck/upstreams/1` returns:
@ -204,16 +200,17 @@ For example, `GET /v1/healthcheck/upstreams/1` returns:
### POST /v1/gc
Introduced since `v2.8`.
Introduced in [v2.8](https://github.com/apache/apisix/releases/tag/2.8).
Trigger a full GC in the http subsystem.
Note that when you enable stream proxy, APISIX will run another Lua VM for the stream subsystem. It won't trigger a full GC in this Lua VM .
Triggers a full garbage collection in the HTTP subsystem.
### Get /v1/routes
**Note**: When stream proxy is enabled, APISIX runs another Lua VM for the stream subsystem. Full garbage collection is not triggered in this VM.
Introduced since `v3.0`.
### GET /v1/routes
Return all routes info in the format below:
Introduced in [v3.0](https://github.com/apache/apisix/releases/tag/3.0).
Returns all configured [Routes](./architecture-design/route.md):
```json
[
@ -249,11 +246,11 @@ Return all routes info in the format below:
]
```
### Get /v1/route/{route_id}
### GET /v1/route/{route_id}
Introduced since `v3.0`.
Introduced in [v3.0](https://github.com/apache/apisix/releases/tag/3.0).
Return specific route info with **route_id** in the format below:
Returns the Route with the specified `route_id`:
```json
{
@ -287,11 +284,11 @@ Return specific route info with **route_id** in the format below:
}
```
### Get /v1/services
### GET /v1/services
Introduced since `v2.11`.
Introduced in [v2.11](https://github.com/apache/apisix/releases/tag/2.11).
Return all services info in the format below:
Returns all the Services:
```json
[
@ -335,11 +332,11 @@ Return all services info in the format below:
]
```
### Get /v1/service/{service_id}
### GET /v1/service/{service_id}
Introduced since `v2.11`.
Introduced in [v2.11](https://github.com/apache/apisix/releases/tag/2.11).
Return specific service info with **service_id** in the format below:
Returns the Service with the specified `service_id`:
```json
{
@ -369,11 +366,11 @@ Return specific service info with **service_id** in the format below:
}
```
### Get /v1/upstreams
### GET /v1/upstreams
Introduced since `v2.11.0`.
Introduced in [v2.11](https://github.com/apache/apisix/releases/tag/2.11).
Dump all upstreams in the format below:
Dumps all Upstreams:
```json
[
@ -410,11 +407,11 @@ Dump all upstreams in the format below:
]
```
### Get /v1/upstream/{upstream_id}
### GET /v1/upstream/{upstream_id}
Introduced since `v2.11.0`.
Introduced in [v2.11](https://github.com/apache/apisix/releases/tag/2.11).
Dump specific upstream info with **upstream_id** in the format below:
Dumps the Upstream with the specified `upstream_id`:
```json
{