Admin API

The Admin API lets users control their deployed Apache APISIX instance. The architecture design gives an idea about how everything fits together.

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).

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

Routes match the client’s request based on defined rules, loads and executes the corresponding plugins, and forwards the request to the specified Upstream.

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

MethodRequest URIRequest BodyDescription
GET/apisix/admin/routesNULLFetches a list of all configured Routes.
GET/apisix/admin/routes/{id}NULLFetches 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}NULLRemoves 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

parameterRequiredTypeDescriptionExample
ttlFalseAuxiliaryRequest expires after the specified target seconds.ttl=1

Request Body Parameters

ParameterRequiredTypeDescriptionExample
nameFalseAuxiliaryIdentifier for the Route.route-xxxx
descFalseAuxiliaryDescription of usage scenarios.route xxxx
uriTrue, can’t be used with urisMatch RulesMatches the uri. For more advanced matching see Router.“/hello”
urisTrue, can’t be used with uriMatch RulesMatches with any one of the multiple uris specified in the form of a non-empty list.[“/hello”, “/word”]
hostFalse, can’t be used with hostsMatch RulesMatches with domain names such as foo.com or PAN domain names like .foo.com.“foo.com”
hostsFalse, can’t be used with hostMatch RulesMatches with any one of the multiple hosts specified in the form of a non-empty list.[“foo.com”, “.bar.com”]
remote_addrFalse, can’t be used with remote_addrsMatch RulesMatches 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_addrsFalse, can’t be used with remote_addrMatch RulesMatches with any one of the multiple remote_addrs specified in the form of a non-empty list.[“127.0.0.1”, “192.0.0.0/8”, “::1”]
methodsFalseMatch RulesMatches with the specified methods. Matches all methods if empty or unspecified.[“GET”, “POST”]
priorityFalseMatch RulesIf 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
varsFalseMatch RulesMatches 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 for more details.[[“arg_name”, “==”, “json”], [“arg_age”, “>”, 18]]
filter_funcFalseMatch RulesMatches 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
pluginsFalsePluginPlugins that are executed during the request/response cycle. See Plugin for more.
scriptFalseScriptUsed for writing arbitrary Lua code or directly calling existing plugins to be executed. See Script for more.
upstreamFalseUpstreamConfiguration of the Upstream.
upstream_idFalseUpstreamId of the Upstream service.
service_idFalseServiceConfiguration of the bound Service.
plugin_config_idFalse, can’t be used with scriptPluginPlugin config bound to the Route.
labelsFalseMatch RulesAttributes of the Route specified as key-value pairs.{“version”:”v2”,”build”:”16”,”env”:”production”}
timeoutFalseAuxiliarySets the timeout (in seconds) for connecting to, and sending and receiving messages between the Upstream and the Route. This will overwrite the timeout value configured in your Upstream.{“connect”: 3, “send”: 3, “read”: 3}
enable_websocketFalseAuxiliaryEnables a websocket. Set to false by default.
statusFalseAuxiliaryEnables the current Route. Set to 1 (enabled) by default.1 to enable, 0 to disable
create_timeFalseAuxiliaryEpoch timestamp (in seconds) of the created time. If missing, this field will be populated automatically.1602883670
update_timeFalseAuxiliaryEpoch timestamp (in seconds) of the updated time. If missing, this field will be populated automatically.1602883670

Example configuration:

  1. {
  2. "id": "1", # id, unnecessary.
  3. "uris": ["/a","/b"], # A set of uri.
  4. "methods": ["GET","POST"], # Can fill multiple methods
  5. "hosts": ["a.com","b.com"], # A set of host.
  6. "plugins": {}, # Bound plugin
  7. "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.
  8. "name": "route-xxx",
  9. "desc": "hello world",
  10. "remote_addrs": ["127.0.0.1"], # A set of Client IP.
  11. "vars": [["http_user", "==", "ios"]], # A list of one or more `[var, operator, val]` elements
  12. "upstream_id": "1", # upstream id, recommended
  13. "upstream": {}, # upstream, not recommended
  14. "timeout": { # Set the upstream timeout for connecting, sending and receiving messages of the route.
  15. "connect": 3,
  16. "send": 3,
  17. "read": 3
  18. },
  19. "filter_func": "", # User-defined filtering function
  20. }

Example API usage:

  1. # Create a route
  2. $ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -i -d '
  3. {
  4. "uri": "/index.html",
  5. "hosts": ["foo.com", "*.bar.com"],
  6. "remote_addrs": ["127.0.0.0/8"],
  7. "methods": ["PUT", "GET"],
  8. "enable_websocket": true,
  9. "upstream": {
  10. "type": "roundrobin",
  11. "nodes": {
  12. "127.0.0.1:1980": 1
  13. }
  14. }
  15. }'
  16. HTTP/1.1 201 Created
  17. Date: Sat, 31 Aug 2019 01:17:15 GMT
  18. ...
  19. # Create a route expires after 60 seconds, then it's deleted automatically
  20. $ curl http://127.0.0.1:9080/apisix/admin/routes/2?ttl=60 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -i -d '
  21. {
  22. "uri": "/aa/index.html",
  23. "upstream": {
  24. "type": "roundrobin",
  25. "nodes": {
  26. "127.0.0.1:1980": 1
  27. }
  28. }
  29. }'
  30. HTTP/1.1 201 Created
  31. Date: Sat, 31 Aug 2019 01:17:15 GMT
  32. ...
  33. # Add an upstream node to the Route
  34. $ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PATCH -i -d '
  35. {
  36. "upstream": {
  37. "nodes": {
  38. "127.0.0.1:1981": 1
  39. }
  40. }
  41. }'
  42. HTTP/1.1 200 OK
  43. ...
  44. After successful execution, upstream nodes will be updated to:
  45. {
  46. "127.0.0.1:1980": 1,
  47. "127.0.0.1:1981": 1
  48. }
  49. # Update the weight of an upstream node to the Route
  50. $ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PATCH -i -d '
  51. {
  52. "upstream": {
  53. "nodes": {
  54. "127.0.0.1:1981": 10
  55. }
  56. }
  57. }'
  58. HTTP/1.1 200 OK
  59. ...
  60. After successful execution, upstream nodes will be updated to:
  61. {
  62. "127.0.0.1:1980": 1,
  63. "127.0.0.1:1981": 10
  64. }
  65. # Delete an upstream node for the Route
  66. $ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PATCH -i -d '
  67. {
  68. "upstream": {
  69. "nodes": {
  70. "127.0.0.1:1980": null
  71. }
  72. }
  73. }'
  74. HTTP/1.1 200 OK
  75. ...
  76. After successful execution, upstream nodes will be updated to:
  77. {
  78. "127.0.0.1:1981": 10
  79. }
  80. # Replace methods of the Route -- array
  81. $ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PATCH -i -d '{
  82. "methods": ["GET", "POST"]
  83. }'
  84. HTTP/1.1 200 OK
  85. ...
  86. After successful execution, methods will not retain the original data, and the entire update is:
  87. ["GET", "POST"]
  88. # Replace upstream nodes of the Route -- sub path
  89. $ curl http://127.0.0.1:9080/apisix/admin/routes/1/upstream/nodes -H'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PATCH -i -d '
  90. {
  91. "127.0.0.1:1982": 1
  92. }'
  93. HTTP/1.1 200 OK
  94. ...
  95. After successful execution, nodes will not retain the original data, and the entire update is:
  96. {
  97. "127.0.0.1:1982": 1
  98. }
  99. # Replace methods of the Route -- sub path
  100. $ curl http://127.0.0.1:9080/apisix/admin/routes/1/methods -H'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PATCH -i -d'["POST", "DELETE", " PATCH"]'
  101. HTTP/1.1 200 OK
  102. ...
  103. After successful execution, methods will not retain the original data, and the entire update is:
  104. ["POST", "DELETE", "PATCH"]
  105. # disable route
  106. $ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PATCH -i -d '
  107. {
  108. "status": 0
  109. }'
  110. HTTP/1.1 200 OK
  111. ...
  112. After successful execution, status nodes will be updated to:
  113. {
  114. "status": 0
  115. }
  116. # enable route
  117. $ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PATCH -i -d '
  118. {
  119. "status": 1
  120. }'
  121. HTTP/1.1 200 OK
  122. ...
  123. After successful execution, status nodes will be updated to:
  124. {
  125. "status": 1
  126. }

Response Parameters

Currently, the response is returned from etcd.

Back to TOC

Service

API: /apisix/admin/services/{id}

A Service is an abstraction of an API (which can also be understood as a set of Route abstractions). It usually corresponds to an upstream service abstraction.

The relationship between Routes and a Service is usually N:1.

Request Methods

MethodRequest URIRequest BodyDescription
GET/apisix/admin/servicesNULLFetches a list of available Services.
GET/apisix/admin/services/{id}NULLFetches 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}NULLRemoves 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

ParameterRequiredTypeDescriptionExample
pluginsFalsePluginPlugins that are executed during the request/response cycle. See Plugin for more.
upstreamFalseUpstreamConfiguration of the Upstream.
upstream_idFalseUpstreamId of the Upstream service.
nameFalseAuxiliaryIdentifier for the Service.service-xxxx
descFalseAuxiliaryDescription of usage scenarios.service xxxx
labelsFalseMatch RulesAttributes of the Service specified as key-value pairs.{“version”:”v2”,”build”:”16”,”env”:”production”}
enable_websocketFalseAuxiliaryEnables a websocket. Set to false by default.
hostsFalseMatch RulesMatches with any one of the multiple hosts specified in the form of a non-empty list.[“foo.com”, “*.bar.com”]
create_timeFalseAuxiliaryEpoch timestamp (in seconds) of the created time. If missing, this field will be populated automatically.1602883670
update_timeFalseAuxiliaryEpoch timestamp (in seconds) of the updated time. If missing, this field will be populated automatically.1602883670

Example configuration:

  1. {
  2. "id": "1", # id
  3. "plugins": {}, # Bound plugin
  4. "upstream_id": "1", # upstream id, recommended
  5. "upstream": {}, # upstream, not recommended
  6. "name": "service-test",
  7. "desc": "hello world",
  8. "enable_websocket": true,
  9. "hosts": ["foo.com"]
  10. }

Example API usage:

  1. $ curl http://127.0.0.1:9080/apisix/admin/services/201 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -i -d '
  2. {
  3. "plugins": {
  4. "limit-count": {
  5. "count": 2,
  6. "time_window": 60,
  7. "rejected_code": 503,
  8. "key": "remote_addr"
  9. }
  10. },
  11. "enable_websocket": true,
  12. "upstream": {
  13. "type": "roundrobin",
  14. "nodes": {
  15. "127.0.0.1:1980": 1
  16. }
  17. }
  18. }'
  19. HTTP/1.1 201 Created
  20. ...
  21. # Add an upstream node to the Service
  22. $ curl http://127.0.0.1:9080/apisix/admin/services/201 -H'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PATCH -i -d '
  23. {
  24. "upstream": {
  25. "nodes": {
  26. "127.0.0.1:1981": 1
  27. }
  28. }
  29. }'
  30. HTTP/1.1 200 OK
  31. ...
  32. After successful execution, upstream nodes will be updated to:
  33. {
  34. "127.0.0.1:1980": 1,
  35. "127.0.0.1:1981": 1
  36. }
  37. # Update the weight of an upstream node to the Service
  38. $ curl http://127.0.0.1:9080/apisix/admin/services/201 -H'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PATCH -i -d '
  39. {
  40. "upstream": {
  41. "nodes": {
  42. "127.0.0.1:1981": 10
  43. }
  44. }
  45. }'
  46. HTTP/1.1 200 OK
  47. ...
  48. After successful execution, upstream nodes will be updated to:
  49. {
  50. "127.0.0.1:1980": 1,
  51. "127.0.0.1:1981": 10
  52. }
  53. # Delete an upstream node for the Service
  54. $ curl http://127.0.0.1:9080/apisix/admin/services/201 -H'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PATCH -i -d '
  55. {
  56. "upstream": {
  57. "nodes": {
  58. "127.0.0.1:1980": null
  59. }
  60. }
  61. }'
  62. HTTP/1.1 200 OK
  63. ...
  64. After successful execution, upstream nodes will be updated to:
  65. {
  66. "127.0.0.1:1981": 10
  67. }
  68. # Replace upstream nodes of the Service
  69. $ curl http://127.0.0.1:9080/apisix/admin/services/201/upstream/nodes -H'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PATCH -i -d '
  70. {
  71. "127.0.0.1:1982": 1
  72. }'
  73. HTTP/1.1 200 OK
  74. ...
  75. After successful execution, upstream nodes will not retain the original data, and the entire update is:
  76. {
  77. "127.0.0.1:1982": 1
  78. }

Response Parameters

Currently, the response is returned from etcd.

Back to TOC

Consumer

API: /apisix/admin/consumers/{username}

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

MethodRequest URIRequest BodyDescription
GET/apisix/admin/consumersNULLFetches a list of all Consumers.
GET/apisix/admin/consumers/{username}NULLFetches specified Consumer by username.
PUT/apisix/admin/consumers{…}Create new Consumer.
DELETE/apisix/admin/consumers/{username}NULLRemoves the Consumer with the specified username.

Request Body Parameters

ParameterRequiredTypeDescriptionExample
usernameTrueNameName of the Consumer.
pluginsFalsePluginPlugins that are executed during the request/response cycle. See Plugin for more.
descFalseAuxiliaryDescription of usage scenarios.customer xxxx
labelsFalseMatch RulesAttributes of the Consumer specified as key-value pairs.{“version”:”v2”,”build”:”16”,”env”:”production”}
create_timeFalseAuxiliaryEpoch timestamp (in seconds) of the created time. If missing, this field will be populated automatically.1602883670
update_timeFalseAuxiliaryEpoch timestamp (in seconds) of the updated time. If missing, this field will be populated automatically.1602883670

Example Configuration:

  1. {
  2. "plugins": {}, # Bound plugin
  3. "username": "name", # Consumer name
  4. "desc": "hello world", # Consumer desc
  5. }

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 API usage:

  1. $ curl http://127.0.0.1:9080/apisix/admin/consumers -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -i -d '
  2. {
  3. "username": "jack",
  4. "plugins": {
  5. "key-auth": {
  6. "key": "auth-one"
  7. },
  8. "limit-count": {
  9. "count": 2,
  10. "time_window": 60,
  11. "rejected_code": 503,
  12. "key": "remote_addr"
  13. }
  14. }
  15. }'
  16. HTTP/1.1 200 OK
  17. Date: Thu, 26 Dec 2019 08:17:49 GMT
  18. ...
  19. {"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

Currently, the response is returned from etcd.

Back to TOC

Upstream

API: /apisix/admin/upstreams/{id}

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

MethodRequest URIRequest BodyDescription
GET/apisix/admin/upstreamsNULLFetch a list of all configured Upstreams.
GET/apisix/admin/upstreams/{id}NULLFetches 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}NULLRemoves 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 equalization algorithm selections, Upstream also supports passive health check and retry for the upstream. See the table below for more details:

NameOptionalDescriptionExample
typerequiredLoad balancing algorithm to be used.
nodesrequired, can’t be used with servicenameIP 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_namerequired, can’t be used with nodesService name used for service discovery.a-bootiful-client
discovery_typerequired, if service_name is usedThe type of service discovery.eureka
hash_onoptionalOnly valid if the type is chash. Supports Nginx variables (vars), custom headers (header), cookie and consumer. Defaults to vars.
keyoptionalOnly 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. 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_
checksoptionalConfigures the parameters for the health check.
retriesoptionalSets 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_timeoutoptionalTimeout to continue with retries. Setting this to 0 disables the retry timeout.
timeoutoptionalSets the timeout (in seconds) for connecting to, and sending and receiving messages to and from the Upstream.
nameoptionalIdentifier for the Upstream.
descoptionalDescription of usage scenarios.
pass_hostoptionalConfigures 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_hostoptionalSpecifies the host of the Upstream request. This is only valid if the pass_host is set to rewrite.
schemeoptionalThe 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’.
labelsoptionalAttributes of the Upstream specified as key-value pairs.{“version”:”v2”,”build”:”16”,”env”:”production”}
create_timeoptionalEpoch timestamp (in seconds) of the created time. If missing, this field will be populated automatically.1602883670
update_timeoptionalEpoch timestamp (in seconds) of the updated time. If missing, this field will be populated automatically.1602883670
tls.client_certoptionalSets the client certificate while connecting to a TLS Upstream.
tls.client_keyoptionalSets the client private key while connecting to a TLS Upstream.
keepalive_pool.sizeoptionalSets keepalive directive dynamically.
keepalive_pool.idle_timeoutoptionalSets keepalive_timeout directive dynamically.
keepalive_pool.requestsoptionalSets keepalive_requests directive dynamically.

An Upstream can be one of the following types:

  • roundrobin: Round robin balancing with weights.
  • chash: Consistent hash.
  • ewma: Pick the node with minimum latency. See 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").

The following should be considered when setting the hash_on value:

  • When set to vars, a key is required. The value of the key can be any of the Nginx variables 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 like $request_uri$remote_addr.
  • When no value is set for either hash_on or key, the key defaults to remote_addr.

The features described below requires APISIX to be run on APISIX-Base:

You can set the scheme to tls, which means “TLS over TCP”.

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.

To allow Upstream to have a separate connection pool, use keepalive_pool. It can be configured by modifying its child fields.

Example Configuration:

  1. {
  2. "id": "1", # id
  3. "retries": 1, # retry times
  4. "timeout": { # Set the timeout for connecting, sending and receiving messages, each is 15 seconds.
  5. "connect":15,
  6. "send":15,
  7. "read":15,
  8. },
  9. "nodes": {"host:80": 100}, # Upstream machine address list, the format is `Address + Port`
  10. # is the same as "nodes": [ {"host": "host", "port": 80, "weight": 100} ],
  11. "type":"roundrobin",
  12. "checks": {}, # Health check parameters
  13. "hash_on": "",
  14. "key": "",
  15. "name": "upstream-for-test",
  16. "desc": "hello world",
  17. "scheme": "http", # The scheme used when communicating with upstream, the default is `http`
  18. }

Example API usage:

Example 1: Create an Upstream and modify the data in nodes

  1. # Create upstream
  2. $ curl http://127.0.0.1:9080/apisix/admin/upstreams/100 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -i -X PUT -d '
  3. {
  4. "type":"roundrobin",
  5. "nodes":{
  6. "127.0.0.1:1980": 1
  7. }
  8. }'
  9. HTTP/1.1 201 Created
  10. ...
  11. # Add a node to the Upstream
  12. $ curl http://127.0.0.1:9080/apisix/admin/upstreams/100 -H'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PATCH -i -d '
  13. {
  14. "nodes": {
  15. "127.0.0.1:1981": 1
  16. }
  17. }'
  18. HTTP/1.1 200 OK
  19. ...
  20. After successful execution, nodes will be updated to:
  21. {
  22. "127.0.0.1:1980": 1,
  23. "127.0.0.1:1981": 1
  24. }
  25. # Update the weight of a node to the Upstream
  26. $ curl http://127.0.0.1:9080/apisix/admin/upstreams/100 -H'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PATCH -i -d '
  27. {
  28. "nodes": {
  29. "127.0.0.1:1981": 10
  30. }
  31. }'
  32. HTTP/1.1 200 OK
  33. ...
  34. After successful execution, nodes will be updated to:
  35. {
  36. "127.0.0.1:1980": 1,
  37. "127.0.0.1:1981": 10
  38. }
  39. # Delete a node for the Upstream
  40. $ curl http://127.0.0.1:9080/apisix/admin/upstreams/100 -H'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PATCH -i -d '
  41. {
  42. "nodes": {
  43. "127.0.0.1:1980": null
  44. }
  45. }'
  46. HTTP/1.1 200 OK
  47. ...
  48. After successful execution, nodes will be updated to:
  49. {
  50. "127.0.0.1:1981": 10
  51. }
  52. # Replace the nodes of the Upstream
  53. $ curl http://127.0.0.1:9080/apisix/admin/upstreams/100/nodes -H'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PATCH -i -d '
  54. {
  55. "127.0.0.1:1982": 1
  56. }'
  57. HTTP/1.1 200 OK
  58. ...
  59. After the execution is successful, nodes will not retain the original data, and the entire update is:
  60. {
  61. "127.0.0.1:1982": 1
  62. }

Example 2: Proxy client request to https Upstream service

  1. Create a route and configure the upstream scheme as https.
  1. $ curl -i http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
  2. {
  3. "uri": "/get",
  4. "upstream": {
  5. "type": "roundrobin",
  6. "scheme": "https",
  7. "nodes": {
  8. "httpbin.org:443": 1
  9. }
  10. }
  11. }'

After successful execution, the scheme when requesting to communicate with the upstream will be https.

  1. Send a request to test.
  1. $ curl http://127.0.0.1:9080/get
  2. {
  3. "args": {},
  4. "headers": {
  5. "Accept": "*/*",
  6. "Host": "127.0.0.1",
  7. "User-Agent": "curl/7.29.0",
  8. "X-Amzn-Trace-Id": "Root=1-6058324a-0e898a7f04a5e95b526bb183",
  9. "X-Forwarded-Host": "127.0.0.1"
  10. },
  11. "origin": "127.0.0.1",
  12. "url": "https://127.0.0.1/get"
  13. }

The request is successful, meaning 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 have been tried or are unavailable.

As the default priority is 0, nodes with negative priority can be configured as a backup.

For example:

  1. {
  2. "uri": "/hello",
  3. "upstream": {
  4. "type": "roundrobin",
  5. "nodes": [
  6. { "host": "127.0.0.1", "port": 1980, "weight": 2000 },
  7. { "host": "127.0.0.1", "port": 1981, "weight": 1, "priority": -1 }
  8. ],
  9. "checks": {
  10. "active": {
  11. "http_path": "/status",
  12. "healthy": {
  13. "interval": 1,
  14. "successes": 1
  15. },
  16. "unhealthy": {
  17. "interval": 1,
  18. "http_failures": 1
  19. }
  20. }
  21. }
  22. }
  23. }

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

Currently, the response is returned from etcd.

Back to TOC

SSL

API:/apisix/admin/ssl/{id}

Request Methods

MethodRequest URIRequest BodyDescription
GET/apisix/admin/sslNULLFetches a list of all configured SSL resources.
GET/apisix/admin/ssl/{id}NULLFetch 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}NULLRemoves the resource with the specified id.

Request Body Parameters

ParameterRequiredTypeDescriptionExample
certTrueCertificateHTTPS certificate.
keyTruePrivate keyHTTPS private key.
certsFalseAn array of certificatesUsed for configuring multiple certificates for the same domain excluding the one provided in the cert field.
keysFalseAn array of private keysPrivate keys to pair with the certs.
client.caFalseCertificateSets the CA certificate that verifies the client. Requires OpenResty 1.19+.
client.depthFalseCertificateSets the verification depth in client certificate chains. Defaults to 1. Requires OpenResty 1.19+.
snisTrueMatch RulesA non-empty array of HTTPS SNI
labelsFalseMatch RulesAttributes of the resource specified as key-value pairs.{“version”:”v2”,”build”:”16”,”env”:”production”}
create_timeFalseAuxiliaryEpoch timestamp (in seconds) of the created time. If missing, this field will be populated automatically.1602883670
update_timeFalseAuxiliaryEpoch timestamp (in seconds) of the updated time. If missing, this field will be populated automatically.1602883670
statusFalseAuxiliaryEnables the current SSL. Set to 1 (enabled) by default.1 to enable, 0 to disable

Example Configuration:

  1. {
  2. "id": "1", # id
  3. "cert": "cert", # Certificate
  4. "key": "key", # Private key
  5. "snis": ["t.com"] # https SNI
  6. }

See Certificate for more examples.

Global Rule

API: /apisix/admin/global_rules/{id}

Sets Plugins which run globally. i.e these Plugins will be run before any Route/Service level Plugins.

Request Methods

MethodRequest URIRequest BodyDescription
GET/apisix/admin/global_rulesNULLFetches a list of all Global Rules.
GET/apisix/admin/global_rules/{id}NULLFetches 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}NULLRemoves 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

ParameterRequiredDescriptionExample
pluginsTruePlugins that are executed during the request/response cycle. See Plugin for more.
create_timeFalseEpoch timestamp (in seconds) of the created time. If missing, this field will be populated automatically.1602883670
update_timeFalseEpoch timestamp (in seconds) of the updated time. If missing, this field will be populated automatically.1602883670

Plugin config

API: /apisix/admin/plugin_configs/{id}

Group of Plugins which can be reused across Routes.

Request Methods

MethodRequest URIRequest BodyDescription
GET/apisix/admin/plugin_configsNULLFetches a list of all Plugin configs.
GET/apisix/admin/plugin_configs/{id}NULLFetches 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}NULLRemoves 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

ParameterRequiredDescriptionExample
pluginsTruePlugins that are executed during the request/response cycle. See Plugin for more.
descFalseDescription of usage scenarios.customer xxxx
labelsFalseAttributes of the Plugin config specified as key-value pairs.{“version”:”v2”,”build”:”16”,”env”:”production”}
create_timeFalseEpoch timestamp (in seconds) of the created time. If missing, this field will be populated automatically.1602883670
update_timeFalseEpoch timestamp (in seconds) of the updated time. If missing, this field will be populated automatically.1602883670

Back to TOC

Plugin Metadata

API: /apisix/admin/plugin_metadata/{plugin_name}

Request Methods

MethodRequest URIRequest BodyDescription
GET/apisix/admin/plugin_metadata/{plugin_name}NULLFetches 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}NULLRemoves metadata for the Plugin specified by the plugin_name.

Request Body Parameters

A JSON object defined according to the metadata_schema of the Plugin ({plugin_name}).

Example Configuration:

  1. $ curl http://127.0.0.1:9080/apisix/admin/plugin_metadata/example-plugin -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -i -X PUT -d '
  2. {
  3. "skey": "val",
  4. "ikey": 1
  5. }'
  6. HTTP/1.1 201 Created
  7. Date: Thu, 26 Dec 2019 04:19:34 GMT
  8. Content-Type: text/plain

Back to TOC

Plugin

API: /apisix/admin/plugins/{plugin_name}

Request Methods

MethodRequest URIRequest BodyDescription
GET/apisix/admin/plugins/listNULLFetches a list of all Plugins.
GET/apisix/admin/plugins/{plugin_name}NULLFetches the specified Plugin by plugin_name.

Request Body Parameters

The Plugin ({plugin_name}) of the data structure.

Example API usage:

  1. $ curl "http://127.0.0.1:9080/apisix/admin/plugins/list" -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1'
  2. ["zipkin","request-id",...]
  3. $ curl "http://127.0.0.1:9080/apisix/admin/plugins/key-auth" -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1'
  4. {"properties":{"disable":{"type":"boolean"}},"additionalProperties":false,"type":"object"}

API: /apisix/admin/plugins?all=true

Get all attributes from all Plugins. Each Plugin has the attributes name, priority, type, schema, consumer_schema and version. Defaults to only HTTP Plugins.

If you need to get attributes from stream Plugins, use /apisix/admin/plugins?all=true&subsystem=stream.

Request Methods

MethodRequest URIRequest BodyDescription
GET/apisix/admin/plugins?all=trueNULLFetches all attributes from all Plugins.

Request Arguments

NameDescriptionDefault
subsystemThe subsystem of the Plugins.http

Back to TOC

Stream Route

API: /apisix/admin/stream_routes/{id}

Route used in the Stream Proxy.

Request Methods

MethodRequest URIRequest BodyDescription
GET/apisix/admin/stream_routesNULLFetches a list of all configured Stream Routes.
GET/apisix/admin/stream_routes/{id}NULLFetches 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}NULLRemoves the Stream Route with the specified id.

Request Body Parameters

ParameterRequiredTypeDescriptionExample
upstreamFalseUpstreamConfiguration of the Upstream.
upstream_idFalseUpstreamId of the Upstream service.
remote_addrFalseIP/CIDRFilters Upstream forwards by matching with client IP.“127.0.0.1/32” or “127.0.0.1”
server_addrFalseIP/CIDRFilters Upstream forwards by matching with APISIX Server IP.“127.0.0.1/32” or “127.0.0.1”
server_portFalseIntegerFilters Upstream forwards by matching with APISIX Server port.9090
sniFalseHostServer Name Indication.“test.com”
protocol.nameFalseStringName of the protocol proxyed by xRPC framework.“redis”
protocol.confFalseConfigurationProtocol-specific configuration.

To learn more about filtering in stream proxies, check this document.

Back to TOC