apisix/doc/admin-api.md

Table of contents

• Route

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.

Request Methods：

Method	Request URI	Request Body	Description
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}/{path}	{...}	Update targeted content

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
desc	False	Auxiliary	Identifies route names, usage scenarios, and more.	customer xxxx
uri	True	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"
host	False	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	Match Rules	The host in the form of a list means that multiple different hosts are allowed, and match any one of them.	{"foo.com", "*.bar.com"}
remote_addr	False	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	Match Rules	The remote_addr in the form of a 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"}
vars	False	Match Rules (only radixtree route is supported)	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 the operator part, the currently supported operators are ==, ~=,>, <, and ~~. For the > and < operators, the result is first converted to number and then compared. See a list of supported operators	{{"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
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	Binded Service configuration, see Service for more
service_protocol	False	Upstream protocol type	only grpc and http are supported	http is the default value; Must set grpc if using gRPC proxy or gRPC transcode

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 response an error.

Example：

# Create a route
$ curl http://127.0.0.1:9080/apisix/admin/routes/1 -X PUT -i -d '
{
    "uri": "/index.html",
    "hosts": ["foo.com", "*.bar.com"],
    "remote_addrs": ["127.0.0.0/8"],
    "methods": ["PUT", "GET"],
    "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 -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
...

Response Parameters

Return response from etcd currently.

Available Operators

Operator	Description	Example
==	Equal	{"arg_name", "==", "json"}
~=	Not Equal	{"arg_name", "~=", "json"}
>	Greater Than	{"arg_age", ">", 24}
<	Less Than	{"arg_age", "<", 24}
~~	Regex	{"arg_name", "~~", "[a-z]+"}

Consider the following example: matching requests whose request name is equal to json, age is greater than 18, and address begins with China:

curl http://127.0.0.1:9080/apisix/admin/routes/1 -X PUT -i -d '
{
    "uri": "/index.html",
    "vars": [
        ["arg_name", "==", "json"],
        ["arg_age", ">", "18"],
        ["arg_address", "~~", "China.*"]
    ],
    "upstream": {
        "type": "roundrobin",
        "nodes": {
            "39.97.63.215:80": 1
        }
    }
}'

Back to TOC