Admin API

Description

The Admin API is a set of APIs serving Apache APIs IX. we can pass parameters to the Admin API to control the APIs IX node. For a better understanding of how it works, see architecture-design Documents in.

When Apache APIs IX is started, by default, the Admin API will listen on port 9080 (port 9443 of HTTPS). You can modify conf/config.yaml File to change the default listening port.

The X-API-KEY that appears below refers to conf / config Apifix.xml in yaml file admin_ key. Key, which is the access token of Admin API.

Route

Address: / apifix / admin / routes / {ID}? ttl=0

Note: Route literally means Route, which matches the client's requests by defining some rules, then loads and executes the corresponding plug-ins according to the matching results, and forwards the requests to the specified Upstream.

Note: when the Admin API is enabled, it will occupy the API prefixed with / apifix / Admin. Therefore, in order to avoid the conflict between your design API and / apifix / Admin, it is recommended to use other ports for the Admin API. You can use conf / config Port in yaml_ Admin to customize the Admin API port.

Request method #

name	Request uri	Request body	explain
GET	/apisix/admin/routes	nothing	Get resource list
GET	/apisix/admin/routes/{id}	nothing	Get resources
PUT	/apisix/admin/routes/{id}	{...}	Create resource based on id
POST	/apisix/admin/routes	{...}	Create a resource, and the id is automatically generated by the background service
DELETE	/apisix/admin/routes/{id}	nothing	Delete resource
PATCH	/apisix/admin/routes/{id}	{...}	Standard PATCH: modify some attributes of the existing Route, and other attributes not involved will be retained as they are; If you want to delete a property, set the value of the property to null to delete it; In particular, when the value of the property to be modified is an array, the property will be fully updated
PATCH	/apisix/admin/routes/{id}/{path}	{...}	SubPath PATCH, specify the attribute to be updated by Route through {path}, and update the data of this attribute in full. Other attributes not involved will be retained as they are. Refer to the following examples for the differences between the two patches

URL request parameters #

name	Optional	type	explain	Example
ttl	Optional	auxiliary	After this time, it will be automatically deleted, unit: second	ttl=1

body request parameters #

name	Optional	type	explain	Example
uri	Required, cannot be used with uris	Matching rules	In addition to full matching such as / foo/bar and / foo/gloo, different methods are used Router It also allows more advanced matching, see Router.	"/hello"
uris	Required, cannot be used with uri	Matching rules	In the form of non empty array, multiple URIs can be matched	["/hello", "/world"]
plugins	Optional	Plugin	See details Plugin
script	Optional	Script	See details Script
upstream	Optional	Upstream	For the enabled Upstream configuration, see Upstream
upstream_id	Optional	Upstream	Enabled upstream id, see Upstream
service_id	Optional	Service	For the bound Service configuration, see Service
plugin_config_id	Optional, cannot be configured with script	Plugin	See the attached Plugin config configuration for details Plugin config
name	Optional	auxiliary	Identify route name	route-xxxx
desc	Optional	auxiliary	Identification description, usage scenario, etc.	Routing xxxx
host	Optional, cannot be used with hosts	Matching rules	Currently requested domain name, such as foo com； Pan domain names are also supported, such as * foo.com.	"foo.com"
hosts	Optional, cannot be used with host	Matching rules	A non empty list of hosts indicates that multiple different hosts are allowed, and any one of them can be matched.	["foo.com", "*.bar.com"]
remote_addr	Optional, cannot be associated with remote_addrs	Matching rules	Client request IP address: 192.168 1.101,192.168. 1.102 and CIDR format support 192.168 1.0/24. In particular, apisid also fully supports IPv6 address matching::: 1, fe80::1, fe80::1/64, etc.	"192.168.1.0/24"
remote_addrs	Optional, cannot be associated with remote_ Use with addr	Matching rules	Remote in non empty list form_ Addr indicates that multiple different IP addresses are allowed, and any one of them can be met.	["127.0.0.1", "192.0.0.0/8", "::1"]
methods	Optional	Matching rules	If it is empty or there is no option, it means there is no method restriction, or it can be a combination of one or more: GET, POST, PUT, DELETE, PATCH, HEAD, OPTIONS, CONNECT, TRACE.	["GET", "POST"]
priority	Optional	Matching rules	If different routes contain the same uri, determine which route is matched first according to the attribute priority. The higher the value, the higher the priority. The default value is 0.	priority = 10
vars	Optional	Matching rules	A list consisting of one or more [var, operator, val] elements, such as: [var, operator, val], [var, operator, val],...]. For example: ["arg_name", "==", "json"], indicating that the current request parameter name is json. The var here is consistent with the naming of the internal variable of Nginx, so you can also use request_uri, host, etc. Please refer to for more details lua-resty-expr	[["arg_name", "==", "json"], ["arg_age", ">", 18]]
filter_func	Optional	Matching rules	User defined filter function. It can be used to realize the matching requirements of special scenes. By default, this function accepts an input parameter named vars, which can be used to obtain the Nginx variable.	function(vars) return vars["arg_name"] == "json" end
labels	Optional	Matching rules	Key value pairs that identify additional properties	{"version":"v2","build":"16","env":"production"}
timeout	Optional	auxiliary	Set the timeout of upstream connection, sending message and receiving message for route. This configuration will override the configuration in upstream timeout option	{"connect": 3, "send": 3, "read": 3}
enable_websocket	Optional	auxiliary	Whether to enable websocket(boolean). The default is false
status	Optional	auxiliary	Whether to enable this route. The default is 1.	1 means enabled, 0 means disabled
create_time	Optional	auxiliary	The epoch timestamp in seconds. If it is not specified, it will be created automatically	1602883670
update_time	Optional	auxiliary	The epoch timestamp in seconds. If it is not specified, it will be created automatically	1602883670

Two points need special attention:

• For the same type of parameters, such as uri and uris, upstream and upstream_id, host and hosts, remote_addr and remote_addrs cannot exist at the same time. You can only choose one of them. If enabled at the same time, the interface will report an error.
• In vars, when getting the value of a cookie, the cookie name is case sensitive. For example, var equal to "cookie_x_foo" and var equal to "cookie_x_foo" represent different cookies.

route object json configuration content:

{
    "id": "1",                  # id, not required
    "uris": ["/a","/b"],        # A set of URL paths
    "methods": ["GET","POST"],  # You can fill in multiple methods
    "hosts": ["a.com","b.com"], # A set of host domain names
    "plugins": {},              # Specifies the plug-in for route binding
    "priority": 0,              # Apifix supports multiple matching methods. Multiple routes may be matched at the same time in a single matching. At this time, the high priority matching is the priority matching
    "name": "route xxx",
    "desc": "hello world",
    "remote_addrs": ["127.0.0.1"],  # A set of client request IP addresses
    "vars": [["http_user", "==", "ios"]], # A list of one or more [var, operator, val] elements
    "upstream_id": "1",         # The id of the upstream object in etcd, which is recommended
    "upstream": {},             # It is recommended not to use the upstream information object
    "timeout": {                # Set the timeout of upstream connection, sending message and receiving message for route.
        "connect": 3,
        "send": 3,
        "read": 3
    },
    "filter_func": "",          # User defined filter function, not required
}

Specific examples:

# 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 valid for 60 seconds and delete it automatically after expiration
$ 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 Update to:
{
    "39.97.63.215:80": 1,
    "39.97.63.216:80": 1
}


# Update the weight of 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.216:80": 10
        }
    }
}'
HTTP/1.1 200 OK
...

After successful execution, upstream nodes Update 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 Update to:
{
    "39.97.63.216:80": 10
}


# methods of replacement 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 The original data will not be retained, and the whole will be updated to:
["GET", "POST"]


# Replace the 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 The original data will not be retained, and the whole will be updated to:
{
    "39.97.63.200:80": 1
}


# Methods of replacement 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 The original data will not be retained, and the whole will be updated to:
["POST", "DELETE", "PATCH"]


# Disable routing
$ 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 Update to:
{
    "status": 0
}


# Enable routing
$ 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 Update to:
{
    "status": 1
}

Response parameters #

At present, it directly returns the result of interaction with etcd.

Service

Address: / apifix / admin / services / {ID}

Note: Service is the abstraction of some kind of API (it can also be understood as the abstraction of a group of routes). It usually corresponds to the upstream Service abstraction one by one. The relationship between Route and Service is usually N:1.

Request method #

name	Request uri	Request body	explain
GET	/apisix/admin/services	nothing	Get resource list
GET	/apisix/admin/services/{id}	nothing	Get resources
PUT	/apisix/admin/services/{id}	{...}	Create resource based on id
POST	/apisix/admin/services	{...}	Create a resource, and the id is automatically generated by the background service
DELETE	/apisix/admin/services/{id}	nothing	Delete resource
PATCH	/apisix/admin/services/{id}	{...}	Standard PATCH, modify some attributes of existing services, and other attributes not involved will be retained as they are; If you want to delete a property, set the value of the property to null to delete it; In particular, when the value of the property to be modified is an array, the property will be fully updated
PATCH	/apisix/admin/services/{id}/{path}	{...}	SubPath PATCH, specify the property to be updated by the Service through {path}, and update the data of this property in full. Other properties not involved will be retained as they are

body request parameters #

name	Optional	type	explain	Example
plugins	Optional	Plugin	See details Plugin
upstream	Upstream or upstream_id one of two	Upstream	For the enabled Upstream configuration, see Upstream
upstream_id	Upstream or upstream_id one of two	Upstream	Enabled upstream id, see Upstream
name	Optional	auxiliary	Identifies the service name.
desc	Optional	auxiliary	Service description, usage scenario, etc.
labels	Optional	Matching rules	Key value pairs that identify additional properties	{"version":"v2","build":"16","env":"production"}
enable_websocket	Optional	auxiliary	Whether to enable websocket(boolean). The default is false
hosts	Optional	Matching rules	A non empty list of hosts indicates that multiple different hosts are allowed, and any one of them can be matched.	["foo.com", "*.bar.com"]
create_time	Optional	auxiliary	The epoch timestamp in seconds. If it is not specified, it will be created automatically	1602883670
update_time	Optional	auxiliary	The epoch timestamp in seconds. If it is not specified, it will be created automatically	1602883670

service object json configuration content:

{
    "id": "1",              # id
    "plugins": {},          # Specifies the plug-in of the service binding
    "upstream_id": "1",     # The id of the upstream object in etcd, which is recommended
    "upstream": {},         # upstream information object, not recommended
    "name": "test svc",  # service name
    "desc": "hello world",  # service description
    "enable_websocket": true, #Start websocket function
    "hosts": ["foo.com"]
}

Specific examples:

# Create a Service
$ 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
        }
    }
}'

# Return results

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 Update to:
{
    "39.97.63.215:80": 1,
    "39.97.63.216:80": 1
}


# Update the weight of 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.216:80": 10
        }
    }
}'
HTTP/1.1 200 OK
...

After successful execution, upstream nodes Update 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 Update to:
{
    "39.97.63.216:80": 10
}


# Replace the 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 The original data will not be retained, and the whole will be updated to:
{
    "39.97.63.200:80": 1
}

Response parameters #

At present, it directly returns the result of interaction with etcd.

Consumer

Address: / apifix / admin / consumers / {username}

Note: Consumer is a Consumer of a certain type of service, which can only be used in conjunction with the user authentication system. The Consumer uses username as the unique ID and only supports the creation of consumers using the HTTP PUT method.

Request method #

name	Request uri	Request body	explain
GET	/apisix/admin/consumers	nothing	Get resource list
GET	/apisix/admin/consumers/{id}	nothing	Get resources
PUT	/apisix/admin/consumers	{...}	Create resource
DELETE	/apisix/admin/consumers/{id}	nothing	Delete resource

body request parameters #

name	Optional	type	explain	Example
username	essential	auxiliary	Consumer name.
plugins	Optional	Plugin	The plug-in configuration corresponding to this Consumer has the highest priority: Consumer > route > service. For specific plug-in configurations, refer to Plugins Chapter.
desc	Optional	auxiliary	consumer description
labels	Optional	Matching rules	Key value pairs that identify additional properties	{"version":"v2","build":"16","env":"production"}
create_time	Optional	auxiliary	The epoch timestamp in seconds. If it is not specified, it will be created automatically	1602883670
update_time	Optional	auxiliary	The epoch timestamp in seconds. If it is not specified, it will be created automatically	1602883670

consumer object json configuration content:

{
    "plugins": {},          # Specifies the plug-in to which the consumer is bound
    "username": "name",     # Required
    "desc": "hello world",  # consumer description
}

The binding authentication plug-in is special. When it needs to be used together 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 need any parameters. At this time, the consumer corresponding to the user is inversely pushed according to the user request data

Example:

# Create a Consumer, specify the authentication plug-in key auth, and open the specific plug-in limit count
$ 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"}

From V2 After version 2, the same consumer can bind multiple authentication plug-ins.

Response parameters #

At present, it directly returns the result of interaction with etcd.

Upstream

Address: / apifix / admin / upstreams / {ID}

Description: Upstream is a virtual host abstraction that performs load balancing on a given number of service nodes according to configuration rules. The address information of the Upstream can be directly configured on the Route (or Service). When there is duplication in the Upstream, you need to use the "reference" method to avoid duplication.

Request method #

name	Request uri	Request body	explain
GET	/apisix/admin/upstreams	nothing	Get resource list
GET	/apisix/admin/upstreams/{id}	nothing	Get resources
PUT	/apisix/admin/upstreams/{id}	{...}	Create resource based on id
POST	/apisix/admin/upstreams	{...}	Create a resource, and the id is automatically generated by the background service
DELETE	/apisix/admin/upstreams/{id}	nothing	Delete resource
PATCH	/apisix/admin/upstreams/{id}	{...}	Standard PATCH, modify some attributes of existing Upstream, and other attributes not involved will be retained as they are; If you want to delete a property, set the value of the property to null to delete it; In particular, when the value of the property to be modified is an array, the property will be fully updated
PATCH	/apisix/admin/upstreams/{id}/{path}	{...}	SubPath PATCH, specify the attribute to be updated in Upstream through {path}, and update the data of this attribute in full. Other attributes that are not involved will be retained as they are.

body request parameters #

In addition to the basic load balancing algorithm selection, apsix Upstream also supports Upstream active and passive health check, retry and other logic. See the table below for details.

name	Optional	type	explain	Example
type	essential	enumeration	Load balancing algorithm
nodes	Required, cannot be associated with service_name	Node	Hash table or array. When it is a hash table, the key of the internal element is the upstream machine address list, Format is address+ (optional) port, where the address part can be either IP or domain name, such as 192.168.1.100:80, foo.com:80, etc. value is the weight of the node. When it is an array, each element in the array is a hash table, including host, weight, optional port and priority. nodes can be empty, which is commonly used as a placeholder. The client hits such an array Upstream will return 502.	192.168.1.100:80
service_name	Required, cannot be used with nodes	string	The service name used in service discovery, see Integrated service discovery registry	a-bootiful-client
discovery_type	Required, if service is set_ name	string	Service discovery type, see Integrated service discovery registry	eureka
key	Condition required	Match type	This option is valid only if the type is chase. Find the corresponding node id according to the key. The same key will always return the same id in the same object. Currently, the supported Nginx built-in variables include URI and server_ name, server_ addr, request_ uri, remote_ port, remote_ addr, query_ string, host, hostname, arg_***， Where ARG_*** Is the request parameter from the URL, Nginx variable list
checks	Optional	health_checker	Configure the parameters of health check. For details, please refer to health-check
retries	Optional	integer	The underlying Nginx retry mechanism is used to pass the request to the next upstream. Retry is enabled by default and the number of node s available at the back end. If a specific number of retries is specified, it overrides the default value. 0 means that the retry mechanism is not enabled.
retry_timeout	Optional	number	Limit whether to continue retrying. If previous requests and retrying requests take too much time, they will not continue retrying. 0 means that the retry timeout mechanism is not enabled.
timeout	Optional	Timeout object	Set the timeout for connecting, sending and receiving messages
hash_on	Optional	auxiliary	hash_on supports vars (Nginx built-in variable), header (custom header), cookie and consumer. The default value is vars
name	Optional	auxiliary	Identify upstream service name, usage scenario, etc.
desc	Optional	auxiliary	Upstream service description, usage scenario, etc.
pass_host	Optional	enumeration	The host setting when the request is sent to the upstream. One of [pass, node, rewrite]. The default is pass. Pass: transparently transmit the host of the client to the upstream; Node: use the host configured in upstream node; Rewrite: use configuration item upstream_ The value of host.
upstream_host	Optional	auxiliary	Specify the host of the upstream request, only in pass_ Valid when host is configured as rewrite.
scheme	Optional	auxiliary	scheme used when communicating with upstream. It needs to be one of ['http', 'https',' grpc ',' grpcs]. The default is' http '.
labels	Optional	Matching rules	Key value pairs that identify additional properties	{"version":"v2","build":"16","env":"production"}
create_time	Optional	auxiliary	The epoch timestamp in seconds. If it is not specified, it will be created automatically	1602883670
update_time	Optional	auxiliary	The epoch timestamp in seconds. If it is not specified, it will be created automatically	1602883670
tls.client_cert	Optional	https certificate	Set the client certificate when communicating with the upstream. See the following for details
tls.client_key	Optional	https certificate private key	Set the client private key when communicating with the upstream. See the following for details
keepalive_pool.size	Optional	auxiliary	Dynamically set the keepalive command. See the following for details
keepalive_pool.idle_timeout	Optional	auxiliary	Set keepalive dynamically_ Timeout instruction, see below for details
keepalive_pool.requests	Optional	auxiliary	Set keepalive dynamically_ Requests instruction, see below for details

type can be one of the following:

• Roundrobin: roundrobin with weight
• Hash: consistent hash
• ewma: select the node with the smallest delay and refer to the calculation details https://en.wikipedia.org/wiki/EWMA_chart
• least_conn: select the node with the smallest (active_conn + 1) / weight. Note that the concept of active connection here is the same as that of Nginx: it is the connection currently being requested.
• The user-defined balancer can be loaded through require ("apifix. Balancer. Your_balancer").

hash_on is complex. Here is a special Description:

1. When set to vars, key is a required parameter. Currently, the supported Nginx built-in variables include URI and server_ name, server_ addr, request_ uri, remote_ port, remote_ addr, query_ string, host, hostname, arg_***， Where ARG_*** Is the request parameter from the URL, Nginx variable list
2. When it is set as header, key is a required parameter, and its value is user-defined header name, that is, "http_key"
3. When set as a cookie, key is a required parameter, and its value is a custom cookie name, that is, "cookie_key". Note that the cookie name is case sensitive. For example, "cookie_x_foo" and "cookie_x_foo" represent different cookies.
4. When it is set to consumer, the key does not need to be set. At this time, the key used in the hash algorithm is the authenticated consumer_name.
5. If the specified hash_ When on and key cannot get the value, they use the default value: remote_addr.

tls.client_cert/key can be used to communicate with upstream mTLS. Their format is the same as cert and key of SSL object. This feature requires APIs IX to run on APISIX-OpenResty.

keepalive_pool allows upstream objects to have their own separate connection pools. Its subordinate fields, such as requests, can use parameters to configure upstream connection retention. This feature requires APIs IX to run on APISIX-OpenResty.

Configuration content of upstream object json:

{
    "id": "1",                  # id
    "retries": 1,               # Request retries
    "timeout": {                # Set the timeout for connecting, sending and receiving messages
        "connect":15,
        "send":15,
        "read":15,
    },
    "nodes": {"host:80": 100},  # Address list of upstream machines in the format of ` address + port`
    # Equivalent to "nodes": [{"host": "host", "port": 80, "weight": 100}],
    "type":"roundrobin",
    "checks": {},               # Configure parameters for health check
    "hash_on": "",
    "key": "",
    "name": "upstream-xxx",     # upstream name
    "desc": "hello world",      # upstream description
    "scheme": "http"            # The scheme used in upstream communication. The default is' http '`
}

Specific examples:

Example 1: create an upstream and modify the data of nodes

# Create an 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 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 Update to:
{
    "39.97.63.215:80": 1,
    "39.97.63.216:80": 1
}


# Update the weight of a node to 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 Update to:
{
    "39.97.63.215:80": 1,
    "39.97.63.216:80": 10
}


# Delete a node for 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 Update to:
{
    "39.97.63.216:80": 10
}


# Replace nodes in 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 successful execution, nodes The original data will not be retained, and the whole will be updated to:
{
    "39.97.63.200:80": 1
}

Example 2: proxy client requests to upstream https services

1. Create a route and configure the scheme of upstream to 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 successful execution, the scheme when requesting communication with the upstream will be https.

2. 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"
}

If the request is successful, it indicates that the agent has taken effect.

be careful:

Nodes can configure their own priorities. A low priority node is accessed only if the high priority node is unavailable or attempted.

Since the default priority is 0, we can configure some nodes with negative priority as backup. for instance:

{
    "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 only at 127.0 0.1 is not available or will not be accessed until it has been tried. So it's 127.0 Backup of 0.1.

Response parameters #

At present, it directly returns the result of interaction with etcd.

SSL

Address: / apifix / admin / SSL / {ID}

Description: SSL

Request method #

name	Request uri	Request body	explain
GET	/apisix/admin/ssl	nothing	Get resource list
GET	/apisix/admin/ssl/{id}	nothing	Get resources
PUT	/apisix/admin/ssl/{id}	{...}	Create resource based on id
POST	/apisix/admin/ssl	{...}	Create a resource, and the id is automatically generated by the background service
DELETE	/apisix/admin/ssl/{id}	nothing	Delete resource

body request parameters #

name	Optional	type	explain	Example
cert	essential	certificate	https certificate
key	essential	Private key	https certificate private key
certs	Optional	Certificate string array	When you want to configure multiple certificates for the same domain name, except that the first certificate needs to be passed through cert, the remaining certificates can be passed through this parameter
keys	Optional	Private key string array	The certificate private key corresponding to certs should correspond to certs one by one
client.ca	Optional	certificate	Set the CA certificate that will be used for client certificate verification. This feature requires OpenResty 1.19+
client.depth	Optional	auxiliary	Set the depth of client certificate verification. The default value is 1. This feature requires OpenResty 1.19+
snis	essential	Matching rules	In the form of non empty array, multiple snis can be matched
labels	Optional	Matching rules	Key value pairs that identify additional properties	{"version":"v2","build":"16","env":"production"}
create_time	Optional	auxiliary	The epoch timestamp in seconds. If it is not specified, it will be created automatically	1602883670
update_time	Optional	auxiliary	The epoch timestamp in seconds. If it is not specified, it will be created automatically	1602883670
status	Optional	auxiliary	Whether to enable this SSL. The default is 1.	1 means enabled, 0 means disabled

ssl object json configuration content:

{
    "id": "1",          # id
    "cert": "cert",     # certificate
    "key": "key",       # Private key
    "snis": ["t.com"]   # SNI sent by client during HTTPS handshake
}

See for more configuration examples certificate.

Global Rule

Address: / apisik / admin / Global_ rules/{id}

Description: set the plug-in to run globally. This type of plug-in takes precedence over all routing level plug-ins.

Request method #

name	Request uri	Request body	explain
GET	/apisix/admin/global_rules	nothing	Get resource list
GET	/apisix/admin/global_rules/{id}	nothing	Get resources
PUT	/apisix/admin/global_rules/{id}	{...}	Create resource based on id
DELETE	/apisix/admin/global_rules/{id}	nothing	Delete resource
PATCH	/apisix/admin/global_rules/{id}	{...}	Standard PATCH, modify some attributes of the existing Global Rule, and other attributes not involved will be retained as they are; If you want to delete a property, set the value of the property to null to delete it; In particular, when the value of the property to be modified is an array, the property will be fully updated
PATCH	/apisix/admin/global_rules/{id}/{path}	{...}	SubPath PATCH, specify the attribute to be updated by Global Rule through {path}, and update the data of this attribute in full. Other attributes not involved will be retained as they are.

body request parameters #

name	Optional	type	explain	Example
plugins	essential	Plugin	See details Plugin
create_time	Optional	auxiliary	The epoch timestamp in seconds. If it is not specified, it will be created automatically	1602883670
update_time	Optional	auxiliary	The epoch timestamp in seconds. If it is not specified, it will be created automatically	1602883670

Plugin Config

Address: / apifix / admin / plugin_ configs/{id}

Description: configure a group of plug-ins that can be reused between routes.

Request method #

name	Request uri	Request body	explain
GET	/apisix/admin/plugin_configs	nothing	Get resource list
GET	/apisix/admin/plugin_configs/{id}	nothing	Get resources
PUT	/apisix/admin/plugin_configs/{id}	{...}	Create resource based on id
DELETE	/apisix/admin/plugin_configs/{id}	nothing	Delete resource
PATCH	/apisix/admin/plugin_configs/{id}	{...}	Standard PATCH, modify some attributes of the existing Plugin Config, and other attributes not involved will be retained as they are; If you want to delete a property, set the value of the property to null to delete it; In particular, when the value of the property to be modified is an array, the property will be fully updated
PATCH	/apisix/admin/plugin_configs/{id}/{path}	{...}	SubPath PATCH, specify the attribute to be updated by Plugin Config through {path}, and update the data of this attribute in full. Other attributes not involved will be retained as they are.

body request parameters #

name	Optional	type	explain	Example
plugins	essential	Plugin	See details Plugin
desc	Optional	auxiliary	Identification description, usage scenario, etc	customer xxxx
labels	Optional	auxiliary	Key value pairs that identify additional properties	{"version":"v2","build":"16","env":"production"}
create_time	Optional	auxiliary	The epoch timestamp in seconds. If it is not specified, it will be created automatically	1602883670
update_time	Optional	auxiliary	The epoch timestamp in seconds. If it is not specified, it will be created automatically	1602883670

Plugin Metadata

Address: / apifix / admin / plugin_ metadata/{plugin_name}

Description: plug in metadata.

Request method #

Method	Request URI	Request body	explain
GET	/apisix/admin/plugin_metadata/{plugin_name}	nothing	Get resources
PUT	/apisix/admin/plugin_metadata/{plugin_name}	{...}	Create resources based on plugin name
DELETE	/apisix/admin/plugin_metadata/{plugin_name}	nothing	Delete resource

body request parameters #

A metadata based on the plug-in ({plugin_name})_ json object of data structure defined by schema.

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

Plugin

Address: / apifix / admin / plugins / {plugin_name}

Description: plug in

Request method #

name	Request uri	Request body	explain
GET	/apisix/admin/plugins/list	nothing	Get resource list
GET	/apisix/admin/plugins/{plugin_name}	nothing	Get resources
GET	/apisix/admin/plugins?all=true	nothing	Get all properties of all plug-ins

body request parameters #

Get the json object of the plug-in ({plugin_name}) 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"}

Address: / apifix / admin / plugins? all=true

Note: all attributes of all plug-ins. Each plug-in includes name, priority, type, schema and consumer_ Schema and version.

By default, this interface only returns the http plug-in. If you need a stream plug-in, you need to use / apifix / admin / plugins? all=true&subsystem=stream.

Request method #

Method	Request URI	Request body	explain
GET	/apisix/admin/plugins?all=true	nothing	Get resources

Request parameters #

name	explain	default
subsystem	Subsystem to which the plug-in belongs	http

Stream Route

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

Description: Stream Route is a route used for TCP/UDP dynamic proxy. See TCP/UDP dynamic proxy A section

Request method #

name	Request uri	Request body	explain
GET	/apisix/admin/stream_routes	nothing	Get resource list
GET	/apisix/admin/stream_routes/{id}	nothing	Get resources
PUT	/apisix/admin/stream_routes/{id}	{...}	Create resource based on id
POST	/apisix/admin/stream_routes	{...}	Create a resource, and the id is automatically generated by the background service
DELETE	/apisix/admin/stream_routes/{id}	nothing	Delete resource

body request parameters #

name	Optional	type	explain	Example
remote_addr	Optional	IP/CIDR	Client IP address	"127.0.0.1/32" or "127.0.0.1"
server_addr	Optional	IP/CIDR	Server IP address	"127.0.0.1/32" or "127.0.0.1"
server_port	Optional	integer	Server port	9090
sni	Optional	Host	Server name indication	"test.com"
upstream	Optional	Upstream	For the enabled Upstream configuration, see Upstream
upstream_id	Optional	Upstream	Enabled upstream id, see Upstream

Control API

The control API can be used to:

• Expose apisex internal status information
• Controls the behavior of the data plane of a single apifix

By default, the control API is enabled, listening to 127.0 0.1:9090. You can modify apifix / conf / config To change the settings in the control section of yaml, as follows:

apisix:
  ...
  enable_control: true
  control:
    ip: "127.0.0.1"
    port: 9090

Note: the control API server should not be configured to listen to public network addresses.

control API added through plug-in

Some plug-ins in Apis IX have added their own control API s. If you are interested in them, please refer to the documentation of the corresponding plug-in.

Plug in independent control API

The following are supported API s:

GET /v1/schema

Introduced from version 2.2

Use the following format to return the json schema used by the apisid instance:

{
    "main": {
        "route": {
            "properties": {...}
        },
        "upstream": {
            "properties": {...}
        },
        ...
    },
    "plugins": {
        "example-plugin": {
            "consumer_schema": {...},
            "metadata_schema": {...},
            "schema": {...},
            "type": ...,
            "priority": 0,
            "version": 0.1
        },
        ...
    },
    "stream-plugins": {
        "mqtt-proxy": {
            ...
        },
        ...
    }
}

Only enabled plug-ins are included in the plugins section of the returned results. Some plug-ins (in the returned results) may be missing, such as consumer_schema or type field, depending on the definition of the plug-in.

GET /v1/healthcheck

Introduced from version 2.3

Use the following format to return the current health check state

[
    {
        "healthy_nodes": [
            {
                "host": "127.0.0.1",
                "port": 1980,
                "priority": 0,
                "weight": 1
            }
        ],
        "name": "upstream#/upstreams/1",
        "nodes": [
            {
                "host": "127.0.0.1",
                "port": 1980,
                "priority": 0,
                "weight": 1
            },
            {
                "host": "127.0.0.2",
                "port": 1988,
                "priority": 0,
                "weight": 1
            }
        ],
        "src_id": "1",
        "src_type": "upstreams"
    },
    {
        "healthy_nodes": [
            {
                "host": "127.0.0.1",
                "port": 1980,
                "priority": 0,
                "weight": 1
            }
        ],
        "name": "upstream#/routes/1",
        "nodes": [
            {
                "host": "127.0.0.1",
                "port": 1980,
                "priority": 0,
                "weight": 1
            },
            {
                "host": "127.0.0.1",
                "port": 1988,
                "priority": 0,
                "weight": 1
            }
        ],
        "src_id": "1",
        "src_type": "routes"
    }
]

Each entry contains the following fields:

• src_type: indicates the source of the health checker. The value is one of [routes,services,upstreams]
• src_id: indicates the id of the object that created the health checker. For example, suppose the Upstream object with id 1 creates a health checker, then src_type is Upstream, src_id is 1
• Name: indicates the name of the health checker
• nodes: the target node of the health checker
• healthy_nodes: indicates the health node detected by the health checker

Users can also use / v1/healthcheck/$src_type/$src_id to get the status of the specified health checker.

For example, GET /v1/healthcheck/upstreams/1 returns:

{
    "healthy_nodes": [
        {
            "host": "127.0.0.1",
            "port": 1980,
            "priority": 0,
            "weight": 1
        }
    ],
    "name": "upstream#/upstreams/1",
    "nodes": [
        {
            "host": "127.0.0.1",
            "port": 1980,
            "priority": 0,
            "weight": 1
        },
        {
            "host": "127.0.0.2",
            "port": 1988,
            "priority": 0,
            "weight": 1
        }
    ],
    "src_id": "1",
    "src_type": "upstreams"
}

POST /v1/gc

Introduced from version 2.8

Trigger a full GC in http subsystem

Note that when you enable stream proxy, apisik will run another Lua virtual machine for the stream subsystem. It will not trigger the full GC in the Lua virtual machine.