[GitHub] [incubator-apisix] membphis commented on a change in pull request #1258: Supplement admin-api-cn.md, add route/service/consumer/upstream/ssl definitions.

[GitBox <gi...@apache.org>]

membphis commented on a change in pull request #1258: Supplement admin-api-cn.md, add route/service/consumer/upstream/ssl definitions.
URL: https://github.com/apache/incubator-apisix/pull/1258#discussion_r392544920
 
 

 ##########
 File path: doc/admin-api-cn.md
 ##########
 @@ -147,3 +173,269 @@ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f13
 
 [Back to TOC](#目录)
 
+## Service
+
+*地址*：/apisix/admin/services/{id}
+
+*说明*：`Service` 是某类 API 的抽象（也可以理解为一组 Route 的抽象）。它通常与上游服务抽象是一一对应的，`Route`
+与 `Service` 之间，通常是 N:1 的关系。
+
+> 请求方法：
+
+|名字      |请求 uri|请求 body|说明        |
+|---------|-------------------------|--|------|
+|GET      |/apisix/admin/services/{id}|无|获取资源|
+|PUT      |/apisix/admin/services/{id}|{...}|根据 id 创建资源|
+|POST     |/apisix/admin/services     |{...}|创建资源，id 由后台服务自动生成|
+|DELETE   |/apisix/admin/services/{id}|无|删除资源|
+|PATCH    |/apisix/admin/services/{id}/{path}|{...}|修改已有 Service 的部分内容，其他不涉及部分会原样保留。|
+
+> body 请求参数：
+
+|名字      |可选项   |类型 |说明        |示例|
+|---------|---------|----|-----------|----|
+|plugins  |可选 |Plugin|详见 [Plugin](architecture-design-cn.md#plugin) ||
+|upstream | upstream 或 upstream_id 两个选一个 |Upstream|启用的 Upstream 配置，详见 [Upstream](architecture-design-cn.md#upstream)||
+|upstream_id| upstream 或 upstream_id 两个选一个 |Upstream|启用的 upstream id，详见 [Upstream](architecture-design-cn.md#upstream)||
+|desc     |可选 |辅助   |标识服务名称、使用场景等。||
+
+serivce 对象 json 配置内容：
+
+```json
+{
+    "id": "1", #id
+    "plugins": {}, #指定 service 绑定的插件
+    "upstream_id": "1", # upstream 对象在 etcd 中的 id ，建议使用此值
+    "upstream": {}, # upstream 信息对象，不建议使用
+    "desc": "hello world", # service 描述
+}
+```
+
+具体示例：
+
+```shell
+# 创建一个Service
+$ 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"}
+```
+
+> 应答参数
+
+目前是直接返回与 etcd 交互后的结果。
+
+[Back to TOC](#目录)
 
 Review comment:
   rename `Back to TOC` to `返回目录`

----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
 
For queries about this service, please contact Infrastructure at:
users@infra.apache.org


With regards,
Apache Git Services