rings-rpc 0.10.0

Rings is a structured peer-to-peer network implementation using WebRTC, Chord algorithm, and full WebAssembly (WASM) support.
Documentation

Rings RPC

rings-node

JSON-RPC API endpoints

Make requests

curl

Url curl to make the requests.

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

javascript

Use fetch to send a JSON-RPC request:

const response = await fetch("http://127.0.0.1:50000", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    jsonrpc: "2.0",
    id: 1,
    method: "nodeInfo",
    params: [],
  }),
});

const result = await response.json();
console.log(result);

JSON-RPC methods

This section lists the rings JSON-RPC API endpoints. You can call these APIs using a variety of tools.

Error codes

The follow list contains all possible error codes and associated messages:

code meaning category
-32000 Internal service error standard
-32001 Connect remote server with error occurred standard
-32002 Push or find pending transport failed standard
-32003 Transport not found standard
-32004 Create new transport failed standard
-32005 Close transport failed standard
-32006 Encode data error standard
-32007 Decode data error standard
-32008 Register ice failed standard
-32009 Create new offer failed standard
-32010 Create new answder failed standard
-32011 Invalid transport id standard
-32012 Invalid did standard
-32013 Invalid method standard
-32014 Send message with error occurred standard
-32015 Permission requires to do something standard
-32016 VNode action error standard
-32017 Register service with error occurred standard
-32018 Invalid data standard
-32019 Invalid message standard
-32020 Invalid service standard
-32021 Invalid address standard
-32022 Invalid auth data standard

Example error response:

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

nodeInfo

return rings node basic information.

REQUEST

POST http://127.0.0.1:50000

HEADERS

Content-Type: application/json

EXAMPLE

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

RESPONSE

  • version - current running node version

BODY

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

connectPeerViaHttp

Connect a peer with peer's jsonrpc endpoint

REQUEST

POST http://127.0.0.1:50000

HEADERS

Content-Type: application/json

EXAMPLE

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

RESPONSE

  • transport_did - the id of transport

EXAMPLE

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

connectWithDid

Connect a peer with peer's did

REQUEST

POST http://127.0.0.1:50000

HEADERS

Content-Type: application/json X-SIGNATURE: YOUR-SIGNATURE

EXAMPLE

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

RESPONSE

EXAMPLE

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

connectWithSeed

Connect a peer with peer's seed

REQUEST

POST http://127.0.0.1:50000

HEADERS

Content-Type: application/json X-SIGNATURE: YOUR-SIGNATURE

EXAMPLE

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

RESPONSE

EXAMPLE

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

createOffer

Create an offer for connection

REQUEST

POST http://127.0.0.1:50000

HEADERS

Content-Type: application/json X-SIGNATURE: YOUR-SIGNATURE

EXAMPLE

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

RESPONSE

  • transport_id: id of the transport
  • ice: ice message

EXAMPLE

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

answerOffer

Answer an offer for connection

REQUEST

POST http://127.0.0.1:50000

HEADERS

Content-Type: application/json X-SIGNATURE: YOUR-SIGNATURE

EXAMPLE

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

RESPONSE

  • transport_id: id of the transport
  • ice: ice message

EXAMPLE

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

listPeers

List all node connected peers

REQUEST

POST http://127.0.0.1:50000

HEADERS

Content-Type: application/json X-SIGNATURE: YOUR-SIGNATURE

EXAMPLE

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

RESPONSE

  • peers - list of connected peers
    • transport_id - id of the transport
    • did - did of remote peer
    • state - transport state

EXAMPLE

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

closeConnection

Close a connected connection with the did of peer

REQUEST

POST http://127.0.0.1:50000

HEADERS

Content-Type: application/json X-SIGNATURE: YOUR-SIGNATURE

EXAMPLE

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

RESPONSE

EXAMPLE

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

listPending

List all pending connections

REQUEST

POST http://127.0.0.1:50000

HEADERS

Content-Type: application/json X-SIGNATURE: YOUR-SIGNATURE

EXAMPLE

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

RESPONSE

  • transport_infos - list of all pending transports
    • transport_id - id of the transport
    • state - state of the transport

EXAMPLE

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

closePendingTransport

Close a specific pending transport

REQUEST

POST http://127.0.0.1:50000

HEADERS

Content-Type: application/json X-SIGNATURE: YOUR-SIGNATURE

EXAMPLE

## Replace YOUR-SIGNATURE with your signature
## Replace TRANSPORT-ID with the transport_id which in listPending
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"

RESPONSE

EXAMPLE

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

sendHttpRequestMessage

Send a http request message to remote peer, the remote peer should provide the service you want to use

REQUEST

POST http://127.0.0.1:50000

HEADERS

Content-Type: application/json X-SIGNATURE: YOUR-SIGNATURE

EXAMPLE

## 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 - service name
    • method - http method
    • path - resource path
    • timeout - timeout of remote request, optional
    • headers - remote request with headers, optional
    • body - request body what you want to send to remote service, optional

RESPONSE

  • tx_id - transaction id

EXAMPLE

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

sendSimpleTextMessage

Send simple text message to a peer

REQUEST

POST http://127.0.0.1:50000

HEADERS

Content-Type: application/json X-SIGNATURE: YOUR-SIGNATURE

EXAMPLE

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

RESPONSE

  • tx_id - transaction id

EXAMPLE

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

sendBackendMessage

Send a message to a peer, routed to the peer's protocol registered under namespace (the extension Envelope model). This replaces the removed sendCustomMessage.

REQUEST

POST http://127.0.0.1:50000

HEADERS

Content-Type: application/json X-SIGNATURE: YOUR-SIGNATURE

PARAMS

  • destination_did - did of the remote peer
  • namespace - protocol namespace the payload is routed to (the Envelope namespace)
  • data - payload bytes, base64-encoded (the payload is binary, so base64 keeps it binary-safe over the JSON wire)

EXAMPLE

## Replace YOUR-SIGNATURE with your signature
## Replace REMOTE-PEER-DID with did of remote peer
## Replace NAMESPACE with the target protocol namespace
## Replace DATA with the base64-encoded payload
curl -X POST \
-H "Content-Type: application/json" \
-H "X-SIGNATURE: YOUR-SIGNATURE" \
--data '{"jsonrpc": "2.0", "id": 1, "method": "sendBackendMessage", "params": {"destination_did": "REMOTE-PEER-DID", "namespace": "NAMESPACE", "data": "DATA"}}' \
"http://127.0.0.1:50000"

RESPONSE

Empty result on success.

EXAMPLE

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

publishMessageToTopic

Publish data message to specific topic

REQUEST

POST http://127.0.0.1:50000

HEADERS

Content-Type: application/json X-SIGNATURE: YOUR-SIGNATURE

EXAMPLE

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

RESPONSE

EXAMPLE

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

fetchMessageToTopic

Fetch message from specific topic

REQUEST

POST http://127.0.0.1:50000

HEADERS

Content-Type: application/json X-SIGNATURE: YOUR-SIGNATURE

EXAMPLE

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

RESPONSE

  • MESSAGES - message vec of specific topic

EXAMPLE

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

registerService

Register custom service to rings network

REQUEST

POST http://127.0.0.1:50000

HEADERS

Content-Type: application/json X-SIGNATURE: YOUR-SIGNATURE

EXAMPLE

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

RESPONSE

EXAMPLE

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

lookupService

Lookup custom service from rings network, you can find all dids of node which provide service you want.

REQUEST

POST http://127.0.0.1:50000

HEADERS

Content-Type: application/json X-SIGNATURE: YOUR-SIGNATURE

EXAMPLE

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

RESPONSE

  • DIDS - did list of nodes which provide service with specific name

EXAMPLE

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