You are viewing a plain text version of this content. The canonical link for it is here.
Posted to notifications@apisix.apache.org by ju...@apache.org on 2019/12/10 03:24:37 UTC
[incubator-apisix] branch master updated: Doc English doc for
admin-api.md (#936)
This is an automated email from the ASF dual-hosted git repository.
juzhiyuan pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/incubator-apisix.git
The following commit(s) were added to refs/heads/master by this push:
new 2e7f41e Doc English doc for admin-api.md (#936)
2e7f41e is described below
commit 2e7f41e503db44b78f9332c3b5990b84725f8bf7
Author: 琚致远 <ju...@apache.org>
AuthorDate: Tue Dec 10 11:24:30 2019 +0800
Doc English doc for admin-api.md (#936)
* Initial Content
resolve https://github.com/apache/incubator-apisix/issues/935
* Update admin-api.md
update Route section
* update request-body parameters
* update Request Body Parameters
* Update admin-api.md
* Update admin-api.md
---
doc/admin-api.md | 143 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 143 insertions(+)
diff --git a/doc/admin-api.md b/doc/admin-api.md
new file mode 100644
index 0000000..3032e6d
--- /dev/null
+++ b/doc/admin-api.md
@@ -0,0 +1,143 @@
+<!--
+#
+# 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)
+
+## 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-cn.md#router) allows more advanced matching, see [Router](architecture-design-cn.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"}|
+|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 `==`, `~=`,`>`, `<`, [...]
+|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-cn.md#plugin) for more ||
+|upstream |False |Upstream|Enabled Upstream configuration, see [Upstream](architecture-design-cn.md#upstream) for more||
+|upstream_id|False |Upstream|Enabled upstream id, see [Upstream](architecture-design-cn.md#upstream) for more ||
+|service_id|False |Service|Binded Service configuration, see [Service](architecture-design-cn.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.
+
+Example：
+
+```shell
+# 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`:
+
+```shell
+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)