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”}
priority	False	Match Rules	If different routes contain the same `uri`, determine which route is matched first based on the attribute `priority`, the default value is 0.	priority = 10
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

Table of contents

Route

Available Operators