docs: add connection doc (#3072)

Signed-off-by: Song Gao <[email protected]>
lf-edge · Aug 2, 2024 · 69525a6 · 69525a6
1 parent fdf78c2
commit 69525a6
Show file tree

Hide file tree

Showing 2 changed files with 84 additions and 86 deletions.
diff --git a/docs/en_US/api/restapi/connection.md b/docs/en_US/api/restapi/connection.md
@@ -1,89 +1,88 @@
 # Manage connection
 
-## Connectivity check
+## Connection management
 
-Check eKuiper connection connectivity via API
+Source/Sink in rules can be created and managed independently in the form of connections.
 
-### sink connection check
+### Create connection
+
+To create a connection, provide the connection's id, type, and configuration parameters. Currently, `mqtt`/`nng`/`httppush`/`websocket`/`edgex`/`sql` type connections are supported. Here we take creating an mqtt connection as an example.
 
 ```shell
-POST http://localhost:9081/metadata/sinks/connection/{sink}
+POST http://localhost:9081/connections
 {
-  "configuration": "xxxx"
+  "id": "connecton-1"
+  "typ":"mqtt",
+  "props": {
+    server: "tcp://127.0.0.1:1883"
+  }
 }
 ```
 
-The sink-side connection check will check the connectivity of the connection based on the incoming sinkType and configuration. Take mysql Sink as an example:
+### Get all connection IDs
 
 ```shell
-POST http://localhost:9081/metadata/sinks/connection/sql
-{
-  "url": "mysql://[email protected]:4000/test",
-  "table": "test",
-  "fields": ["a","b","c"]
-}
+GET http://localhost:9081/connections
 ```
 
-### Source side connection check
+### Get all connection status
 
 ```shell
-POST http://localhost:9081/metadata/sources/connection/{source}
-{
-  "configuration": "xxxx"
-}
+GET http://localhost:9081/connections/status
 ```
 
-The source-side connection check will check the connectivity of the connection based on the incoming sourceType and configuration. Take mysql Source as an example:
+### Get a single connection status
 
 ```shell
-POST http://localhost:9081/metadata/sources/connection/sql
-{
-  "url": "mysql://[email protected]:4000/test",
-}
+GET http://localhost:9081/connection/{id}
 ```
 
-## Manage websocket connection
-
-Manage websocket endpoint connection in eKuiper through REST API
+### Delete a single connection
 
-## create websocket endpoint
+When deleting a connection, it will check whether there are rules using the connection. If there are rules using the connection, the connection cannot be deleted.
 
 ```shell
-POST http://localhost:9081/connection/websocket
+DELETE http://localhost:9081/connection/{id}
 ```
 
-example：
+## Connectivity check
 
-```json
-{
-  "endpoint": "/xxxx"
-}
-```
+Check eKuiper connection connectivity via API
 
-## delete websocket endpoint
+### sink connection check
 
 ```shell
-DELETE http://localhost:9081/connection/websocket
+POST http://localhost:9081/metadata/sinks/connection/{sink}
+{
+  "configuration": "xxxx"
+}
 ```
 
-example：
+The sink-side connection check will check the connectivity of the connection based on the incoming sinkType and configuration. Take mysql Sink as an example:
 
-```json
+```shell
+POST http://localhost:9081/metadata/sinks/connection/sql
 {
-  "endpoint": "/xxxx"
+  "url": "mysql://[email protected]:4000/test",
+  "table": "test",
+  "fields": ["a","b","c"]
 }
 ```
 
-## query websocket endpoint
+### Source side connection check
 
 ```shell
-GET http://localhost:9081/connection/websocket
+POST http://localhost:9081/metadata/sources/connection/{source}
+{
+  "configuration": "xxxx"
+}
 ```
 
-example：
+The source-side connection check will check the connectivity of the connection based on the incoming sourceType and configuration. Take mysql Source as an example:
 
-```json
+```shell
+POST http://localhost:9081/metadata/sources/connection/sql
 {
-  "endpoint": "/xxxx"
+  "url": "mysql://[email protected]:4000/test",
 }
 ```
diff --git a/docs/zh_CN/api/restapi/connection.md b/docs/zh_CN/api/restapi/connection.md
@@ -1,89 +1,88 @@
 # 连接管理
 
-## 连通性检查
+## 连接管理
 
-通过 API 检查 eKuiper 连接的连通性
+规则中的 Source/Sink 可以以连接的形式被独立创建、管理。
 
-### sink 端连接检查
+### 创建连接
+
+创建连接去要提供连接的 id, 类型和配置参数。目前已经支持了 `mqtt`/`nng`/`httppush`/`websocket`/`edgex`/`sql` 类型的连接，这里以创建 mqtt 连接为例。
 
 ```shell
-POST http://localhost:9081/metadata/sinks/connection/{sink}
+POST http://localhost:9081/connections
 {
-  "configuration": "xxxx"
+  "id": "connecton-1"
+  "typ":"mqtt",
+  "props": {
+    server: "tcp://127.0.0.1:1883"
+  }
 }
 ```
 
-sink 端连接检查会根据传入的 sinkType 和配置来检查连接的连通性，以 mysql Sink 为例:
+### 获取所有连接 ID
 
 ```shell
-POST http://localhost:9081/metadata/sinks/connection/sql
-{
-  "url": "mysql://[email protected]:4000/test",
-  "table": "test",
-  "fields": ["a","b","c"]
-}
+GET http://localhost:9081/connections
 ```
 
-### source 端连接检查
+### 获取所有连接状态
 
 ```shell
-POST http://localhost:9081/metadata/sources/connection/{source}
-{
-  "configuration": "xxxx"
-}
+GET http://localhost:9081/connections/status
 ```
 
-source 端连接检查会根据传入的 sourceType 和配置来检查连接的连通性，以 mysql Source 为例:
+### 获取单个连接状态
 
 ```shell
-POST http://localhost:9081/metadata/sources/connection/sql
-{
-  "url": "mysql://[email protected]:4000/test",
-}
+GET http://localhost:9081/connection/{id}
 ```
 
-## websocket 连接管理
-
-通过 API 管理 eKuiper websocket 的连接
+### 删除单个连接
 
-### 创建 websocket endpoint
+删除连接时会是否有规则正在使用连接，如果存在规则正在使用连接，那么连接将无法被删除。
 
 ```shell
-POST http://localhost:9081/connection/websocket
+DELETE http://localhost:9081/connection/{id}
 ```
 
-请求示例：
+## 连通性检查
 
-```json
-{
-  "endpoint": "/xxxx"
-}
-```
+通过 API 检查 eKuiper 连接的连通性
 
-### 删除 websocket endpoint
+### sink 端连接检查
 
 ```shell
-DELETE http://localhost:9081/connection/websocket
+POST http://localhost:9081/metadata/sinks/connection/{sink}
+{
+  "configuration": "xxxx"
+}
 ```
 
-请求示例：
+sink 端连接检查会根据传入的 sinkType 和配置来检查连接的连通性，以 mysql Sink 为例:
 
-```json
+```shell
+POST http://localhost:9081/metadata/sinks/connection/sql
 {
-  "endpoint": "/xxxx"
+  "url": "mysql://[email protected]:4000/test",
+  "table": "test",
+  "fields": ["a","b","c"]
 }
 ```
 
-### 查看 websocket endpoint
+### source 端连接检查
 
 ```shell
-GET http://localhost:9081/connection/websocket
+POST http://localhost:9081/metadata/sources/connection/{source}
+{
+  "configuration": "xxxx"
+}
 ```
 
-请求示例：
+source 端连接检查会根据传入的 sourceType 和配置来检查连接的连通性，以 mysql Source 为例:
 
-```json
+```shell
+POST http://localhost:9081/metadata/sources/connection/sql
 {
-  "endpoint": "/xxxx"
+  "url": "mysql://[email protected]:4000/test",
 }
 ```