test/apisix
1
0
Fork 0
mirror of https://gitee.com/iresty/apisix.git synced 2024-12-15 01:11:58 +08:00
Code Issues Actions Packages Projects Releases Wiki Activity
2999541c49
apisix/doc/admin-api.md
nic-chen 502310bef6
feat: support different modes to pass host to upstream (#2132) 
* test: using `httpbin.org` for test cases.
* doc: add doc
* remove golang apt repository and runtime in travis.
* download proto file
Co-authored-by: Yuansheng <membphis@gmail.com>
2020-08-30 22:43:28 +08:00

26 KiB
Raw Blame History

Table of Contents

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} {...} 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. customer-xxxx
desc False Auxiliary route description, 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. 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 {{"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 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.

Config Example:

{
    "id": "1",                  # id, unnecessary.
    "uri": "/release/a",        # uri
    "uris": ["/a","/b"],        # A set of uri, URL 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.
    "name": "route-xxx",
    "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：

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


# 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"]

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

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/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. customer-xxxx
desc False Auxiliary service usage scenarios, and more. customer xxxx

Config Example:

{
    "id": "1",          # id
    "plugins": {},      # Bound plugin
    "upstream_id": "1", # upstream id, recommended
    "upstream": {},     # upstream, not recommended
    "name": "service-test",
    "desc": "hello world",
}

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"
        }
    },
    "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/{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 for more
desc False Auxiliary Identifies route names, usage scenarios, and more. customer xxxx

Config Example:

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

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

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/{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
type required roundrobin supports the weight of the load, chash consistency hash,ewma minimum latency ,pick one of them.see https://en.wikipedia.org/wiki/EWMA_chart for details
nodes required if k8s_deployment_info not configured 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.
k8s_deployment_info required if nodes not configured fields: namespace、deploy_name、service_name、port、backend_type, port is number, backend_type is pod or service, others is string.
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. 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.
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. 0 means disable retry mechanism.
enable_websocket optional enable websocket(boolean), default false.
timeout optional Set the timeout for connection, sending and receiving messages.
name optional Identifies upstream names
desc optional upstream usage scenarios, and more.
pass_host optional pass pass the client request host, node not pass the client request host, using the upstream node host, rewrite rewrite host by the configured upstream_host.
upstream_host optional This option is only valid if the pass_host is rewrite.

Config Example:

{
    "id": "1",                  # id
    "retries": 1,               # retry times
    "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`
    "k8s_deployment_info": {    # kubernetes deployment info
        "namespace": "test-namespace",
        "deploy_name": "test-deploy-name",
        "service_name": "test-service-name",
        "backend_type": "pod",    # pod or service
        "port": 8080
    },
    "type":"roundrobin",        # chash or roundrobin
    "checks": {},               # Health check parameters
    "hash_on": "",
    "key": "",
    "name": "upstream-for-test",
    "desc": "hello world",
}

Example：

$ curl http://127.0.0.1:9080/apisix/admin/upstreams/100  -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -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
...


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

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

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

Back to TOC