--- title: Admin API --- ## Table of Contents - [Description](#description) - [Route](#route) - [Service](#service) - [Consumer](#consumer) - [Upstream](#upstream) - [SSL](#ssl) - [Global Rule](#global-rule) - [Plugin Config](#plugin-config) - [Plugin Metadata](#plugin-metadata) - [Plugin](#plugin) - [Stream Route](#stream-route) ## Description 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). 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. ## Route *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. 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`. ### 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 | ### URI Request Parameters | parameter | Required | Type | Description | Example | | --------- | -------- | --------- | ---------------------------- | ------- | | ttl | False | Auxiliary | Expires after 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 | Binded Service configuration, see [Service](architecture-design/service.md) for more | | | plugin_config_id | False, can't be used with `script` | Plugin | Binded 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 | 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: ```shell { "id": "1", # id, unnecessary. "uris": ["/a","/b"], # A set of uri. "methods": ["GET","POST"], # Can fill multiple methods "hosts": ["a.com","b.com"], # A set of host. "plugins": {}, # Bound plugin "priority": 0, # If different routes contain the same `uri`, determine which route is matched first based on the attribute` priority`, the default value is 0. "name": "route-xxx", "desc": "hello world", "remote_addrs": ["127.0.0.1"], # A set of Client IP. "vars": [["http_user", "==", "ios"]], # A list of one or more `[var, operator, val]` elements "upstream_id": "1", # upstream id, recommended "upstream": {}, # upstream, not recommended "timeout": { # Set the upstream timeout for connecting, sending and receiving messages of the route. "connect": 3, "send": 3, "read": 3 }, "filter_func": "", # User-defined filtering function } ``` Example： ```shell # Create a route $ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -i -d ' { "uri": "/index.html", "hosts": ["foo.com", "*.bar.com"], "remote_addrs": ["127.0.0.0/8"], "methods": ["PUT", "GET"], "enable_websocket": true, "upstream": { "type": "roundrobin", "nodes": { "39.97.63.215:80": 1 } } }' HTTP/1.1 201 Created Date: Sat, 31 Aug 2019 01:17:15 GMT ... # Create a route expires after 60 seconds, then it's deleted automatically $ curl http://127.0.0.1:9080/apisix/admin/routes/2?ttl=60 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -i -d ' { "uri": "/aa/index.html", "upstream": { "type": "roundrobin", "nodes": { "39.97.63.215:80": 1 } } }' HTTP/1.1 201 Created Date: Sat, 31 Aug 2019 01:17:15 GMT ... # Add an upstream node to the Route $ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PATCH -i -d ' { "upstream": { "nodes": { "39.97.63.216:80": 1 } } }' HTTP/1.1 200 OK ... After successful execution, upstream nodes will be updated to: { "39.97.63.215:80": 1, "39.97.63.216:80": 1 } # Update the weight of an upstream node to the Route $ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PATCH -i -d ' { "upstream": { "nodes": { "39.97.63.216:80": 10 } } }' HTTP/1.1 200 OK ... After successful execution, upstream nodes will be updated to: { "39.97.63.215:80": 1, "39.97.63.216:80": 10 } # Delete an upstream node for the Route $ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PATCH -i -d ' { "upstream": { "nodes": { "39.97.63.215:80": null } } }' HTTP/1.1 200 OK ... After successful execution, upstream nodes will be updated to: { "39.97.63.216:80": 10 } # Replace methods of the Route -- array $ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PATCH -i -d '{ "methods": ["GET", "POST"] }' HTTP/1.1 200 OK ... After successful execution, methods will not retain the original data, and the entire update is: ["GET", "POST"] # Replace upstream nodes of the Route -- sub path $ curl http://127.0.0.1:9080/apisix/admin/routes/1/upstream/nodes -H'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PATCH -i -d ' { "39.97.63.200:80": 1 }' HTTP/1.1 200 OK ... After successful execution, nodes will not retain the original data, and the entire update is: { "39.97.63.200:80": 1 } # Replace methods of the Route -- sub path $ curl http://127.0.0.1:9080/apisix/admin/routes/1/methods -H'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PATCH -i -d'["POST", "DELETE", " PATCH"]' HTTP/1.1 200 OK ... After successful execution, methods will not retain the original data, and the entire update is: ["POST", "DELETE", "PATCH"] # disable route $ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PATCH -i -d ' { "status": 0 }' HTTP/1.1 200 OK ... After successful execution, status nodes will be updated to: { "status": 0 } # enable route $ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PATCH -i -d ' { "status": 1 }' HTTP/1.1 200 OK ... After successful execution, status nodes will be updated to: { "status": 1 } ``` ### Response Parameters Return response from etcd currently. [Back to TOC](#table-of-contents) ## Service *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. ### 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 | ### 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`. | | | 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 | Config Example: ```shell { "id": "1", # id "plugins": {}, # Bound plugin "upstream_id": "1", # upstream id, recommended "upstream": {}, # upstream, not recommended "name": "service-test", "desc": "hello world", "enable_websocket": true, } ``` Example： ```shell $ curl http://127.0.0.1:9080/apisix/admin/services/201 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -i -d ' { "plugins": { "limit-count": { "count": 2, "time_window": 60, "rejected_code": 503, "key": "remote_addr" } }, "enable_websocket": true, "upstream": { "type": "roundrobin", "nodes": { "39.97.63.215:80": 1 } } }' HTTP/1.1 201 Created ... # Add an upstream node to the Service $ curl http://127.0.0.1:9080/apisix/admin/services/201 -H'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PATCH -i -d ' { "upstream": { "nodes": { "39.97.63.216:80": 1 } } }' HTTP/1.1 200 OK ... After successful execution, upstream nodes will be updated to: { "39.97.63.215:80": 1, "39.97.63.216:80": 1 } # Update the weight of an upstream node to the Service $ curl http://127.0.0.1:9080/apisix/admin/services/201 -H'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PATCH -i -d ' { "upstream": { "nodes": { "39.97.63.216:80": 10 } } }' HTTP/1.1 200 OK ... After successful execution, upstream nodes will be updated to: { "39.97.63.215:80": 1, "39.97.63.216:80": 10 } # Delete an upstream node for the Service $ curl http://127.0.0.1:9080/apisix/admin/services/201 -H'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PATCH -i -d ' { "upstream": { "nodes": { "39.97.63.215:80": null } } }' HTTP/1.1 200 OK ... After successful execution, upstream nodes will be updated to: { "39.97.63.216:80": 10 } # Replace upstream nodes of the Service $ curl http://127.0.0.1:9080/apisix/admin/services/201/upstream/nodes -H'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PATCH -i -d ' { "39.97.63.200:80": 1 }' HTTP/1.1 200 OK ... After successful execution, upstream nodes will not retain the original data, and the entire update is: { "39.97.63.200:80": 1 } ``` ### Response Parameters Return response from etcd currently. [Back to TOC](#table-of-contents) ## Consumer *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. ### 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 | ### 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 | Config Example: ```shell { "plugins": {}, # Bound plugin "username": "name", # Consumer name "desc": "hello world", # Consumer desc } ``` 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. Example: ```shell $ curl http://127.0.0.1:9080/apisix/admin/consumers -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -i -d ' { "username": "jack", "plugins": { "key-auth": { "key": "auth-one" }, "limit-count": { "count": 2, "time_window": 60, "rejected_code": 503, "key": "remote_addr" } } }' HTTP/1.1 200 OK Date: Thu, 26 Dec 2019 08:17:49 GMT ... {"node":{"value":{"username":"jack","plugins":{"key-auth":{"key":"auth-one"},"limit-count":{"time_window":60,"count":2,"rejected_code":503,"key":"remote_addr","policy":"local"}}},"createdIndex":64,"key":"\/apisix\/consumers\/jack","modifiedIndex":64},"prevNode":{"value":"{\"username\":\"jack\",\"plugins\":{\"key-auth\":{\"key\":\"auth-one\"},\"limit-count\":{\"time_window\":60,\"count\":2,\"rejected_code\":503,\"key\":\"remote_addr\",\"policy\":\"local\"}}}","createdIndex":63,"key":"\/apisix\/consumers\/jack","modifiedIndex":63},"action":"set"} ``` Since `v2.2`, we can bind multiple authentication plugins to the same consumer. ### Response Parameters Return response from etcd currently. [Back to TOC](#table-of-contents) ## Upstream *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`. ### 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 | ### 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. |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. The value is one of ['http', 'https', 'grpc', 'grpcs'], default to 'http'.|| |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 priviate 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|| `type` can be one of: * `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. `hash_on` can be set to different types: 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. `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. This feature requires APISIX to run on [APISIX-OpenResty](./how-to-build.md#6-build-openresty-for-apisix). `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. This feature requires APISIX to run on [APISIX-OpenResty](./how-to-build.md#6-build-openresty-for-apisix). **Config Example:** ```shell { "id": "1", # id "retries": 1, # retry times "timeout": { # Set the timeout for connecting, sending and receiving messages. "connect":15, "send":15, "read":15, }, "nodes": {"host:80": 100}, # Upstream machine address list, the format is `Address + Port` # is the same as "nodes": [ {"host": "host", "port": 80, "weight": 100} ], "type":"roundrobin", "checks": {}, # Health check parameters "hash_on": "", "key": "", "name": "upstream-for-test", "desc": "hello world", "scheme": "http", # The scheme used when communicating with upstream, the default is `http` } ``` **Example:** Example 1: Create an upstream and modify the data of `nodes` ```shell # Create upstream $ curl http://127.0.0.1:9080/apisix/admin/upstreams/100 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -i -X PUT -d ' { "type":"roundrobin", "nodes":{ "39.97.63.215:80": 1 } }' HTTP/1.1 201 Created ... # Add a node to the Upstream $ curl http://127.0.0.1:9080/apisix/admin/upstreams/100 -H'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PATCH -i -d ' { "nodes": { "39.97.63.216:80": 1 } }' HTTP/1.1 200 OK ... After successful execution, nodes will be updated to: { "39.97.63.215:80": 1, "39.97.63.216:80": 1 } # Update the weight of a node to the Upstream $ curl http://127.0.0.1:9080/apisix/admin/upstreams/100 -H'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PATCH -i -d ' { "nodes": { "39.97.63.216:80": 10 } }' HTTP/1.1 200 OK ... After successful execution, nodes will be updated to: { "39.97.63.215:80": 1, "39.97.63.216:80": 10 } # Delete a node for the Upstream $ curl http://127.0.0.1:9080/apisix/admin/upstreams/100 -H'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PATCH -i -d ' { "nodes": { "39.97.63.215:80": null } }' HTTP/1.1 200 OK ... After successful execution, nodes will be updated to: { "39.97.63.216:80": 10 } # Replace the nodes of the Upstream $ curl http://127.0.0.1:9080/apisix/admin/upstreams/100/nodes -H'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PATCH -i -d ' { "39.97.63.200:80": 1 }' HTTP/1.1 200 OK ... After the execution is successful, nodes will not retain the original data, and the entire update is: { "39.97.63.200:80": 1 } ``` Example 2: How to proxy client request to `https` upstream service 1. Create a route and configure the upstream scheme as `https`. ```shell $ curl -i http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d ' { "uri": "/get", "upstream": { "type": "roundrobin", "scheme": "https", "nodes": { "httpbin.org:443": 1 } } }' ``` After the execution is successful, the scheme when requesting to communicate with the upstream will be `https`. 2. Send a request for testing. ```shell $ curl http://127.0.0.1:9080/get { "args": {}, "headers": { "Accept": "*/*", "Host": "127.0.0.1", "User-Agent": "curl/7.29.0", "X-Amzn-Trace-Id": "Root=1-6058324a-0e898a7f04a5e95b526bb183", "X-Forwarded-Host": "127.0.0.1" }, "origin": "127.0.0.1", "url": "https://127.0.0.1/get" } ``` The request is successful, which means that the proxy upstream `https` is valid. **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. As the default priority is 0, we can configure nodes with negative priority as the backup. For example: ```json { "uri": "/hello", "upstream": { "type": "roundrobin", "nodes": [ {"host": "127.0.0.1", "port": 1980, "weight": 2000}, {"host": "127.0.0.2", "port": 1980, "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`. ### Response Parameters Return response from etcd currently. [Back to TOC](#table-of-contents) ## SSL *API*：/apisix/admin/ssl/{id} *Description*：SSL. ### 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 | ### 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 | Config Example: ```shell { "id": "1", # id "cert": "cert", # Certificate "key": "key", # Private key "snis": ["t.com"] # https SNI } ``` More examples can be found in [Certificate](./certificate.md). ## Global Rule *API*：/apisix/admin/global_rules/{id} *Description*: Set plugins which run globally. Those 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. | ### 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 | ## Plugin config *API*：/apisix/admin/plugin_configs/{id} *Description*: Provide a 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. | ### 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 | [Back to TOC](#table-of-contents) ## Plugin Metadata *API*：/apisix/admin/plugin_metadata/{plugin_name} *Description*: plugin metadata. ### 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 | ### Request Body Parameters A json object with a data structure defined according to `metadata_schema` of the plugin ({plugin_name}). Config Example: ```shell $ curl http://127.0.0.1:9080/apisix/admin/plugin_metadata/example-plugin -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -i -X PUT -d ' { "skey": "val", "ikey": 1 }' HTTP/1.1 201 Created Date: Thu, 26 Dec 2019 04:19:34 GMT Content-Type: text/plain ``` [Back to TOC](#table-of-contents) ## Plugin *API*：/apisix/admin/plugins/{plugin_name} *Description*: plugin ### 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 | ### Request Body Parameters Get the plugin ({plugin_name}) of the data structure. Example： ```shell $ curl "http://127.0.0.1:9080/apisix/admin/plugins/list" -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' ["zipkin","request-id",...] $ curl "http://127.0.0.1:9080/apisix/admin/plugins/key-auth" -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' {"properties":{"disable":{"type":"boolean"}},"additionalProperties":false,"type":"object"} ``` *API*：/apisix/admin/plugins?all=true *Description*: all the attributes of all plugins, each plugin includes `name`, `priority`, `type`, `schema`, `consumer_schema` and `version`. ### Request Methods | Method | Request URI | Request Body | Description | | ------ | ------------------------------ | ------------ | -------------- | | GET | /apisix/admin/plugins?all=true | NULL | Fetch resource | [Back to TOC](#table-of-contents) ## Stream Route *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. ### 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 | ### Request Body Parameters | Parameter | Required | Type | Description | Example | | ---------------- | ------| -------- | ------| -----| | remote_addr | False | IP | client IP | "127.0.0.1" | | server_addr | False | IP | server IP | "127.0.0.1" | | server_port | False | Integer | server port | 9090 | | sni | False | Host | server name indication | "test.com" | [Back to TOC](#table-of-contents)