apisix/doc/admin-api.md

<!--
#
# Licensed to the Apache Software Foundation (ASF) under one or more
# contributor license agreements.  See the NOTICE file distributed with
# this work for additional information regarding copyright ownership.
# The ASF licenses this file to You under the Apache License, Version 2.0
# (the "License"); you may not use this file except in compliance with
# the License.  You may obtain a copy of the License at
#
#     http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
#
-->


Table of contents
===

* [Route](#route)
* [Service](#service)
* [Consumer](#consumer)
* [Upstream](#upstream)
* [SSL](#ssl)

## 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](architecture-design.md#router) allows more advanced matching, see [Router](architecture-design.md#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`. 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 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](#available-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](architecture-design.md#plugin) for more ||
|upstream |False |Upstream|Enabled Upstream configuration, see [Upstream](architecture-design.md#upstream) for more||
|upstream_id|False |Upstream|Enabled upstream id, see [Upstream](architecture-design.md#upstream) for more ||
|service_id|False |Service|Binded Service configuration, see [Service](architecture-design.md#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.

Config Example:

```shell
{
    "id": "1",                  # id, unnecessary.
    "uri": "/release/a",        # uri
    "uris": ["/a","/b"],        # A set of uri, uri and uris need only have a non-empty one.
    "methods": ["GET","POST"],  # Can fill multiple methods
    "host": "aa.com",           # host
    "hosts": ["a.com","b.com"], # A set of host. Host and hosts only need to be non-empty one.
    "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.
    "desc": "hello world",
    "remote_addr": "127.0.0.1", # Client IP
    "remote_addrs": ["127.0.0.1"], # A set of Client IP. Remote_addr and remo-te_addrs only need to be non-empty one.
    "vars": [],                 # A list of one or more `{var, operator, val}` elements
    "upstream_id": "1",         # upstream id, recommended
    "upstream": {},             # upstream, not recommended
    "filter_func": "",          # User-defined filtering function
}
```

Example：

```shell
# 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"],
    "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
...

```

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

```shell
curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -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)

## 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/{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/routes/{id}/{path}|{...}|Update targeted content|

> Request Body Parameters：

|Parameter      |Required   |Type |Description        |Example|
|---------|---------|----|-----------|----|
|plugins  |False |Plugin|See [Plugin](architecture-design.md#plugin) for more ||
|upstream |False |Upstream|Enabled Upstream configuration, see [Upstream](architecture-design.md#upstream) for more||
|upstream_id|False |Upstream|Enabled upstream id, see [Upstream](architecture-design.md#upstream) for more ||
|desc     |False |Auxiliary   |Identifies route names, usage scenarios, and more.|customer xxxx|

Config Example:

```shell
{
    "id": "1",          # id
    "plugins": {},      # Bound plugin
    "upstream_id": "1", # upstream id, recommended
    "upstream": {},     # upstream, not recommended
    "desc": "hello world",
}
```

Example：

```shell
$ curl http://127.0.0.1:9080/apisix/admin/services/201 -X PUT -i -d '
{
    "plugins": {
        "limit-count": {
            "count": 2,
            "time_window": 60,
            "rejected_code": 503,
            "key": "remote_addr"
        }
    },
    "upstream": {
        "type": "roundrobin",
        "nodes": {
            "39.97.63.215:80": 1
        }
    }
}'

HTTP/1.1 201 Created
Date: Thu, 26 Dec 2019 03:48:47 GMT
Content-Type: text/plain
Transfer-Encoding: chunked
Connection: keep-alive
Access-Control-Allow-Origin: *
Access-Control-Allow-Credentials: true
Access-Control-Expose-Headers: *
Access-Control-Max-Age: 3600
Server: APISIX web server

{"node":{"value":{"upstream":{"nodes":{"39.97.63.215:80":1},"type":"roundrobin"},"plugins":{"limit-count":{"time_window":60,"count":2,"rejected_code":503,"key":"remote_addr","policy":"local"}}},"createdIndex":60,"key":"\/apisix\/services\/201","modifiedIndex":60},"action":"set"}
```

> Response Parameters

Return response from etcd currently.

[Back to TOC](#table-of-contents)

## Consumer

*API*：/apisix/admin/consumers/{id}

*Description*：Consumers are consumers of certain types of services and can only be used in conjunction with a user authentication system.

> Request Methods：

|Method      |Request URI|Request Body|Description        |
|---------|-------------------------|--|------|
|GET      |/apisix/admin/consumers/{id}|NULL|Fetch resource|
|PUT      |/apisix/admin/consumers/{id}|{...}|Create resource by ID|
|POST     |/apisix/admin/consumers     |{...}|Create resource, and ID is generated by server|
|DELETE   |/apisix/admin/consumers/{id}|NULL|Remove resource|

> Request Body Parameters：

|Parameter      |Required   |Type |Description        |Example|
|---------|---------|----|-----------|----|
|username|True|Name|Consumer name||
|plugins  |False |Plugin|See [Plugin](architecture-design.md#plugin) for more ||
|desc     |False |Auxiliary   |Identifies route names, usage scenarios, and more.|customer xxxx|

Config Example:

```shell
{
    "id": "1",              # id
    "plugins": {},          # Bound plugin
    "username": "name",     # Consumer name
    "desc": "hello world",  # Consumer desc
}
```

The binding authentication and authorization 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:

```shell
$ curl http://127.0.0.1:9080/apisix/admin/consumers/2 -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"}
```

> Response Parameters

Return response from etcd currently.

[Back to TOC](#table-of-contents)

## 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/{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}/{path}|{...}|Update targeted content|

> 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|
|-------         |-----|------|
|type            |required|`roundrobin` supports the weight of the load, `chash` consistency hash, pick one of them.|
|nodes           |required|Hash table, the key of the internal element is the upstream machine address list, the format is `Address + Port`, where the address part can be IP or domain name, such as `192.168.1.100:80`, `foo.com:80`, etc. Value is the weight of the node. In particular, when the weight value is `0`, it has a special meaning, which usually means that the upstream node is invalid and never wants to be selected.|
|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             |required|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](http://nginx.org/en/docs/varindex.html). 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_id` 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](health-check.md).|
|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 backend nodes. If `retries` option is explicitly set, it will override the default value.|
|enable_websocket|optional| enable `websocket`(boolean), default `false`.|
|timeout|optional| Set the timeout for connection, sending and receiving messages. |
|desc     |optional|Identifies route names, usage scenarios, and more.|

Config Example:

```shell
{
    "id": "1",                  # id
    "retries": 0,               # retry time
    "timeout": {                # Set the timeout for connection, sending and receiving messages.
        "connect":15,
        "send":15,
        "read":15,
    },
    "enable_websocket": true,
    "nodes": {"host:80": 100},  # Upstream machine address list, the format is `Address + Port`
    "type":"roundrobin",        # chash or roundrobin
    "checks": {},               # Health check parameters
    "hash_on": "",
    "key": "",
    "desc": "hello world",
}
```

Example：

```shell
$ curl http://127.0.0.1:9080/apisix/admin/upstreams/100 -i -X PUT -d '
> {
>     "type": "roundrobin",
>     "nodes": {
>         "127.0.0.1:80": 1,
>         "127.0.0.2:80": 2,
>         "foo.com:80": 3
>     }
> }'
HTTP/1.1 201 Created
Date: Thu, 26 Dec 2019 04:19:34 GMT
Content-Type: text/plain
...

{"node":{"value":{"nodes":{"127.0.0.1:80":1,"foo.com:80":3,"127.0.0.2:80":2},"type":"roundrobin"},"createdIndex":61,"key":"\/apisix\/upstreams\/100","modifiedIndex":61},"action":"set"}

```

> Response Parameters

Return response from etcd currently.

[Back to TOC](#table-of-contents)

## SSL

*API*：/apisix/admin/ssl/{id}

*Description*：SSL.

> Request Methods：

|Method      |Request URI|Request Body|Description        |
|---------|-------------------------|--|------|
|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|Public key|https Public key||
|key|True|Private key|https Private key||
|sni|True|Match Rules|https SNI||

Config Example:

```shell
{
    "id": "1",      # id
    "cert": "cert", # Public key
    "key": "key",   # Private key
    "sni": "sni"    # https SNI
}
```

[Back to TOC](#table-of-contents)