Skip to content

Latest commit

 

History

History
987 lines (778 loc) · 70.3 KB

admin-api.md

File metadata and controls

987 lines (778 loc) · 70.3 KB
Raw
title
Admin API

Table of Contents

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.

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 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 allows more advanced matching, see Router 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 [["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 for more
script False Script See Script for more
upstream False Upstream Enabled Upstream configuration, see Upstream for more
upstream_id False Upstream Enabled upstream id, see Upstream for more
service_id False Service Bound Service configuration, see Service for more
plugin_config_id False, can't be used with script Plugin Bound plugin config object, see Plugin Config 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 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:

{
    "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：

# 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

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 for more
upstream False Upstream Enabled Upstream configuration, see Upstream for more
upstream_id False Upstream Enabled upstream id, see Upstream 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

Config Example:

{
    "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,
    "hosts": ["foo.com"]
}

Example：

$ 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

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

{
    "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:

$ 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

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 for more details a-bootiful-client
discovery_type required, if service_name is used the type of service discovery, see discovery 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. 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.
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 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

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.
  • user-defined balancer which can be loaded via require("apisix.balancer.your_balancer").

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, without the prefix '$'.
  2. When it is header, the key is required. It is equal to "http_key".
  3. 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.
  4. When it is consumer, the key is optional. The key is the consumer_name set by authentication plugin.
  5. When it is vars_combinations, the key is required. The key can be any Nginx builtin variables combinations, such as $request_uri$remote_addr.
  6. 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.

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.

Config Example:

{
    "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

# 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.
$ 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.

  1. Send a request for testing.
$ 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:

{
    "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

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:

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

More examples can be found in Certificate.

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

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:

$ 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

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：

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

By default, this API only returns the http plugins. If you need 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

Request Arguments

Name Description Default
subsystem the subsystem of plugins http

Back to TOC

Stream Route

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

Description：Stream Route is the route used in the stream proxy. See Stream Proxy 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"
upstream False Upstream Upstream configuration, see Upstream for more details
upstream_id False Upstream specify the upstream id, see Upstream for more details

Back to TOC