6个版本 (破坏性更新)

0.7.0	2024年5月1日
0.6.0	2024年3月28日
0.5.1	2024年1月2日
0.3.0	2023年9月21日
0.2.6	2023年6月29日

#1930 在网络编程

每月26次下载
在rings-node中使用

GPL-3.0许可证

160KB
3K SLoC

环RPC

JSON-RPC API端点

发送请求

curl

使用curl curl发送请求。

curl -X POST \
-H "Content-Type: application/json" \
--data '{"jsonrpc": "2.0", "id": 1, "method": "nodeInfo", "params": []}' \
"http://127.0.0.1:50000"

javascript

待办事项

JSON-RPC方法

本节列出rings JSON-RPC API端点。您可以使用各种工具调用这些API。

错误代码

以下列表包含所有可能的错误代码及其关联消息

代码	含义	类别
-32000	内部服务错误	标准
-32001	连接远程服务器时发生错误	标准
-32002	推送或查找待处理传输失败	标准
-32003	找不到传输	标准
-32004	创建新的`transport`失败	标准
-32005	关闭`transport`失败	标准
-32006	编码数据错误	标准
-32007	解码数据错误	标准
-32008	注册ICE失败	标准
-32009	创建新的`offer`失败	标准
-32010	创建新的`answer`失败	标准
-32011	无效的传输ID	标准
-32012	无效的did	标准
-32013	无效的方法	标准
-32014	发送消息时发生错误	标准
-32015	需要进行某些操作的权限	标准
-32016	VNode操作错误	标准
-32017	注册服务时发生错误	标准
-32018	无效数据	标准
-32019	无效消息	标准
-32020	无效服务	标准
-32021	无效地址	标准
-32022	无效认证数据	标准

示例错误响应

{
    "id": 1,
    "jsonrpc": "2.0",
    "error": {
        "code": -32000,
        "message": "internal service error",
    }
}

nodeInfo

返回环节点的基本信息。

请求

POSThttp://127.0.0.1:50000

标题

内容-类型:application/json

示例

curl -X POST \
-H "Content-Type: application/json" \
--data '{"jsonrpc": "2.0", "id": 1, "method": "nodeInfo", "params": []}' \
"http://127.0.0.1:50000"

响应

version - 当前运行节点版本

正文

{
    "jsonrpc": "2.0",
    "id": 1,
    "result": {
        "version": "0.0.1"
    }
}

connectPeerViaHttp

使用对等的jsonrpc端点连接对等

请求

POSThttp://127.0.0.1:50000

标题

内容-类型:application/json

示例

## Replace REMOTE-JSONRPC-ENDPOINT with the url what you want to connect
curl -X POST \
-H "Content-Type: application/json" \
--data '{"jsonrpc": "2.0", "id": 1, "method": "connectPeerViaHttp", "params": ["REMOTE-JSONRPC-ENDPOINT"]}' \
"http://127.0.0.1:50000"

响应

transport_did - 传输的ID

示例

{
    "jsonrpc": "2.0",
    "id": 1,
    "result": [
        "abcd-1234"
    ]
}

connectWithDid

使用对等的did连接对等

请求

POSThttp://127.0.0.1:50000

标题

内容-类型: application/json X-签名: YOUR-签名

示例

## Replace REMOTE-PEER-DID with the did what you want to connect
## Replace YOUR-SIGNATURE with your signature
curl -X POST \
-H "Content-Type: application/json" \
-H "X-SIGNATURE: YOUR-SIGNATURE" \
--data '{"jsonrpc": "2.0", "id": 1, "method": "connectPeerWithDid", "params": ["REMOTE-PEER-DID"]}' \
"http://127.0.0.1:50000"

响应

示例

{
    "jsonrpc": "2.0",
    "id": 1,
    "result": null
}

connectWithSeed

使用种子连接对等节点

请求

POSThttp://127.0.0.1:50000

标题

内容-类型: application/json X-签名: YOUR-签名

示例

## Replace REMOTE-PEER-SEED with the did what you want to connect
## Replace YOUR-SIGNATURE with your signature
curl -X POST \
-H "Content-Type: application/json" \
-H "X-SIGNATURE: YOUR-SIGNATURE" \
--data '{"jsonrpc": "2.0", "id": 1, "method": "connectPeerWithSeed", "params": ["REMOTE-PEER-SEED"]}' \
"http://127.0.0.1:50000"

响应

示例

{
    "jsonrpc": "2.0",
    "id": 1,
    "result": null
}

createOffer

创建连接的提议

请求

POSThttp://127.0.0.1:50000

标题

内容-类型: application/json X-签名: YOUR-签名

示例

## Replace REMOTE-PEER-SEED with the did what you want to connect
## Replace YOUR-SIGNATURE with your signature
curl -X POST \
-H "Content-Type: application/json" \
-H "X-SIGNATURE: YOUR-SIGNATURE" \
--data '{"jsonrpc": "2.0", "id": 1, "method": "createOffer", "params": [REMOTE-PEER-DID]}' \
"http://127.0.0.1:50000"

响应

transport_id: 传输的 ID
ice: ICE 消息

示例

{
    "jsonrpc": "2.0",
    "id": 1,
    "result": {
        "transport_id": "1234",
        "ice": "abcd1234",
    }
}

answerOffer

应答连接提议

请求

POSThttp://127.0.0.1:50000

标题

内容-类型: application/json X-签名: YOUR-签名

示例

## Replace REMOTE-PEER-SEED with the did what you want to connect
## Replace YOUR-SIGNATURE with your signature
curl -X POST \
-H "Content-Type: application/json" \
-H "X-SIGNATURE: YOUR-SIGNATURE" \
--data '{"jsonrpc": "2.0", "id": 1, "method": "createOffer", "params": ["REMOTE-PEER-SEED"]}' \
"http://127.0.0.1:50000"

响应

transport_id: 传输的 ID
ice: ICE 消息

示例

{
    "jsonrpc": "2.0",
    "id": 1,
    "result": {
        "transport_id": "1234",
        "ice": "abcd1234",
    }
}

listPeers

列出所有连接的对等节点

请求

POSThttp://127.0.0.1:50000

标题

内容-类型: application/json X-签名: YOUR-签名

示例

## Replace YOUR-SIGNATURE with your signature
curl -X POST \
-H "Content-Type: application/json" \
-H "X-SIGNATURE: YOUR-SIGNATURE" \
--data '{"jsonrpc": "2.0", "id": 1, "method": "listPeers", "params": []}' \
"http://127.0.0.1:50000"

响应

peers - 连接的对等节点列表
- transport_id - 传输的 ID
- did - 远程对等节点的 did
- state - 传输状态

示例

{
    "jsonrpc": "2.0",
    "id": 1,
    "result": [
        {
            "did": "abcd1234"
            "transport_id": "1234",
            "state": "connected",
        }
    ]
}

closeConnection

关闭与对等节点 did 相关联的连接

请求

POSThttp://127.0.0.1:50000

标题

内容-类型: application/json X-签名: YOUR-签名

示例

## Replace REMOTE-PEER-DID with ice what you got from others
## Replace YOUR-SIGNATURE with your signature
curl -X POST \
-H "Content-Type: application/json" \
-H "X-SIGNATURE: YOUR-SIGNATURE" \
--data '{"jsonrpc": "2.0", "id": 1, "method": "closeConnection", "params": ["REMOTE-PEER-DID"]}' \
"http://127.0.0.1:50000"

响应

示例

{
    "jsonrpc": "2.0",
    "id": 1,
    "result": {}
}

listPendings

列出所有挂起的连接

请求

POSThttp://127.0.0.1:50000

标题

内容-类型: application/json X-签名: YOUR-签名

示例

## Replace YOUR-SIGNATURE with your signature
curl -X POST \
-H "Content-Type: application/json" \
-H "X-SIGNATURE: YOUR-SIGNATURE" \
--data '{"jsonrpc": "2.0", "id": 1, "method": "closeConnection", "params": []}' \
"http://127.0.0.1:50000"

响应

transport_infos - 所有挂起传输的列表
- transport_id - 传输的 ID
- state - 传输的状态

示例

{
    "jsonrpc": "2.0",
    "id": 1,
    "result": [
        {
            "transport_id": "abcd1234",
            "state": "new"
        }
    ]
}

closePendingTransport

关闭特定的挂起传输

请求

POSThttp://127.0.0.1:50000

标题

内容-类型: application/json X-签名: YOUR-签名

示例

## Replace YOUR-SIGNATURE with your signature
## Replace TRANSPORT-ID with the transport_id which in listPendings
curl -X POST \
-H "Content-Type: application/json" \
-H "X-SIGNATURE: YOUR-SIGNATURE" \
--data '{"jsonrpc": "2.0", "id": 1, "method": "closePendingTransport", "params": ["TRANSPORT-ID"]}' \
"http://127.0.0.1:50000"

响应

示例

{
    "jsonrpc": "2.0",
    "id": 1,
    "result": {}
}

sendHttpRequestMessage

向远程对等节点发送 HTTP 请求消息，远程对等节点应提供您希望使用的服务

请求

POSThttp://127.0.0.1:50000

标题

内容-类型: application/json X-签名: YOUR-签名

示例

## Replace YOUR-SIGNATURE with your signature
## Replace REMOTE-PEER-DID with did of remote peer
## Replace HTTP-REQUEST-ARG with your request arguments
curl -X POST \
-H "Content-Type: application/json" \
-H "X-SIGNATURE: YOUR-SIGNATURE" \
--data '{"jsonrpc": "2.0", "id": 1, "method": "sendSimpleTextMessage", "params": ["REMOTE-PEER-DID", {HTTP-REQUEST-ARG}]}' \
"http://127.0.0.1:50000"

HTTP-REQUEST-ARG
- name - 服务名称
- method - HTTP 方法
- path - 资源路径
- timeout - 远程请求的超时时间，可选
- headers - 带有头部的远程请求，可选
- body - 想要发送到远程服务的请求体，可选

响应

tx_id - 事务 ID

示例

{
    "jsonrpc": "2.0",
    "id": 1,
    "result": {
         "tx_id": "abcd1234"
    }
}

sendSimpleTextMessage

向对等节点发送简单文本消息

请求

POSThttp://127.0.0.1:50000

标题

内容-类型: application/json X-签名: YOUR-签名

示例

## Replace YOUR-SIGNATURE with your signature
## Replace REMOTE-PEER-DID with did of remote peer
## Replace TEXT with what you want to send
curl -X POST \
-H "Content-Type: application/json" \
-H "X-SIGNATURE: YOUR-SIGNATURE" \
--data '{"jsonrpc": "2.0", "id": 1, "method": "sendSimpleTextMessage", "params": ["REMOTE-PEER-DID", "TEXT"]}' \
"http://127.0.0.1:50000"

响应

tx_id - 事务 ID

示例

{
    "jsonrpc": "2.0",
    "id": 1,
    "result": {
         "tx_id": "abcd1234"
    }
}

sendCustomMessage

向对等节点发送自定义消息

请求

POSThttp://127.0.0.1:50000

标题

内容-类型: application/json X-签名: YOUR-签名

示例

## Replace YOUR-SIGNATURE with your signature
## Replace REMOTE-PEER-DID with did of remote peer
## Replace MESSAGE-TYPE with type of your message
## Replace DATA with message payload after base64
curl -X POST \
-H "Content-Type: application/json" \
-H "X-SIGNATURE: YOUR-SIGNATURE" \
--data '{"jsonrpc": "2.0", "id": 1, "method": "sendCustomMessage", "params": ["REMOTE-PEER-DID", "MESSAGE-TYPE", "DATA"]}' \
"http://127.0.0.1:50000"

响应

tx_id - 事务 ID

示例

{
    "jsonrpc": "2.0",
    "id": 1,
    "result": {
         "tx_id": "abcd1234"
    }
}

publishMessageToTopic

将数据消息发布到特定主题

请求

POSThttp://127.0.0.1:50000

标题

内容-类型: application/json X-签名: YOUR-签名

示例

## Replace YOUR-SIGNATURE with your signature
## Replace TOPIC with message topic
## Replace DATA with message payload after base64
curl -X POST \
-H "Content-Type: application/json" \
-H "X-SIGNATURE: YOUR-SIGNATURE" \
--data '{"jsonrpc": "2.0", "id": 1, "method": "publishMessageToTOpic", "params": ["TOPIC", "DATA"]}' \
"http://127.0.0.1:50000"

响应

示例

{
    "jsonrpc": "2.0",
    "id": 1,
    "result": {}
}

fetchMessageToTopic

从特定主题获取消息

请求

POSThttp://127.0.0.1:50000

标题

内容-类型: application/json X-签名: YOUR-签名

示例

## Replace YOUR-SIGNATURE with your signature
## Replace TOPIC with message topic
## Replace DATA with message payload after base64
curl -X POST \
-H "Content-Type: application/json" \
-H "X-SIGNATURE: YOUR-SIGNATURE" \
--data '{"jsonrpc": "2.0", "id": 1, "method": "fetchMessageToTopic", "params": ["TOPIC", "INDEX"]}' \
"http://127.0.0.1:50000"

响应

MESSAGES - 特定主题的消息向量

示例

{
    "jsonrpc": "2.0",
    "id": 1,
    "result": [
        "topic_message",
    ]
}

registerService

将自定义服务注册到 rings 网络

请求

POSThttp://127.0.0.1:50000

标题

内容-类型: application/json X-签名: YOUR-签名

示例

## Replace YOUR-SIGNATURE with your signature
## Replace NAME with the service name what you want to publish to rings network
curl -X POST \
-H "Content-Type: application/json" \
-H "X-SIGNATURE: YOUR-SIGNATURE" \
--data '{"jsonrpc": "2.0", "id": 1, "method": "registerService", "params": ["NAME"]}' \
"http://127.0.0.1:50000"

响应

示例

{
    "jsonrpc": "2.0",
    "id": 1,
    "result": {}
}

lookupService

从 rings 网络查找自定义服务，您可以找到所有提供所需服务的节点的 did。

请求

POSThttp://127.0.0.1:50000

标题

内容-类型: application/json X-签名: YOUR-签名

示例

## Replace YOUR-SIGNATURE with your signature
## Replace NAME with the service name what you want to lookup in rings network
curl -X POST \
-H "Content-Type: application/json" \
-H "X-SIGNATURE: YOUR-SIGNATURE" \
--data '{"jsonrpc": "2.0", "id": 1, "method": "lookupService", "params": ["NAME"]}' \
"http://127.0.0.1:50000"

响应

DIDS - 提供具有特定名称服务的节点的 did 列表

示例

{
    "jsonrpc": "2.0",
    "id": 1,
    "result": [
        "did1",
        "did2",
    ]
}

pollMessage

使用此方法，您可以拉取该节点接收到的消息，以提供您的自定义服务。但我们建议使用 websocket 端点实时获取消息。

请求

POSThttp://127.0.0.1:50000

标题

内容-类型: application/json X-签名: YOUR-签名

示例

## Replace YOUR-SIGNATURE with your signature
## Replace WAIT with a bool value, true will block the request, until new message receive.
curl -X POST \
-H "Content-Type: application/json" \
-H "X-SIGNATURE: YOUR-SIGNATURE" \
--data '{"jsonrpc": "2.0", "id": 1, "method": "pollMessage", "params": ["WAIT"]}' \
"http://127.0.0.1:50000"

响应

message - 接收到的自定义消息

示例

{
    "jsonrpc": "2.0",
    "id": 1,
    "result": {
      "message": {
          message_type: 1,
          data: "base64 text"
      }
    }
}

依赖项

~4–21MB
~265K SLoC