Diode API Docs

Updated 8 months ago by Zach

Enabling the Diode API

This API runs on every Diode app instance, and is disabled by default.

The API is device-wide. To enable the API on your device:

1. Open the Diode app (version 1.10.7 or later)
2. Navigate to any Zone and any Channel, it doesn't matter which Channel
3. Send the following chat command to the Channel: /sysconfig remote-api enable.

1. Next, a token will need generated. To generate a token, send this chat command: /sysconfig remote-api generate-token
2. To view the newly generated token, use this command: /sysconfig remote-api view-token

1. The API is now enabled device-wide and a token has been obtained. The device is now ready to accept API requests by whoever has the token. Here are some other helpful commands:
   1. Regenerate Token (Note: This will replace the previous token):
      /sysconfig remote-api generate-token
   2. Disable API:
      /sysconfig remote-api disable
   3. API Status:
      /sysconfig remote-api status
   4. API Version:
      /sysconfig remote-api version

Calling the API (HTTP)

A valid request is an HTTP POST request containing the following two headers and a JSON-RPC 2.0 payload.

There are two ways to reach the API endpoint:

• Via the Diode Web2 Gateway (most convenient, use anywhere):
  https://<device_address>.diode.link/api/json_rpc
• Direct via Web3 (most secure, requires web3 pipe between caller and device where the API is enabled):
  http://<device_address>.diode/api/json_rpc

Headers:

Content-Type: application/json

Authorization: Bearer <bearer_token>

JSON-RPC 2.0 Payload Format:

{"jsonrpc":"2.0","method":"<method>","params":["<param1>", "<param2>", ..., <paramN>], "id":N}

Curl Example:

curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer <bearer_token>" -d '{"jsonrpc":"2.0","method":"<method>","params":["<param1>", "<param2>", ..., <paramN>], "id":N}' https://<device_address>.diode.link/api/json_rpc

Calling the API (WebSocket)

To use advanced methods such as "subscribe_channel", the WebSocket API can be used. Once connected, the WebSocket payload must contain a valid JSON-RPC 2.0 method call. Authentication is done via the "authenticate" method when calling the WebSocket API . Once authenticated successfully, any method can be called.

Like the HTTP API, there are two ways to reach the WebSockets API endpoint:

• Via the Diode Web2 Gateway (most convenient, use anywhere):
  ws://<device_address>.diode.link/api/json_rpc/ws
• Direct via Web3 (most secure, requires web3 pipe between caller and device where the API is enabled):
  ws://<device_address>.diode/api/json_rpc/ws

Here is an example of a python script calling the API via WebSockets.

API Methods

"ping"

Call

{"jsonrpc":"2.0","method":"ping","id":1}

Success Response

{"jsonrpc":"2.0","result":"The RPC endpoint has been successfully contacted.","id":1}

"send_message"

Call

{"jsonrpc":"2.0","method":"send_message","params":["<zone_id>", "<channel_id>", "<message_text>"], "id":1}

Success Response

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

"subscribe_channel" (WebSocket only)

Call

{"jsonrpc":"2.0","method":"subscribe_channel","params":["<zone_id>", "<channel_id>"], "id":1}

Success Response

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

Incoming Message(s)

{
  "jsonrpc":"2.0",
  "result":
      {
        "messages":
          [
            {
              "attributes": {
                "mentions": <peer_address>,
                "reply": <unix_timestamp>,
                "t": <hex>
              },
              "creation_time": <unix_timestamp>,
              "edited_at": <unix_timestamp>,
              "group_id": <channel_id>,
              "message": <string>,
              "reply_to": <message_object>,
              "sender": {
                "address": <sender_hex_address>,
                "domain": <sender_bns_name>,
                "nickname": <sender_nickname>
                }
            },
            ...
          ]
      },
  "id":1
}

"subscribe_all_channels_in_zone" (WebSocket only)

Call

{"jsonrpc":"2.0","method":"subscribe_all_channels_in_zone","params":["<zone_id>"], "id":1}

Success Response

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

Incoming Message(s)

# Same format as the "subscribe_channel" function.

"authenticate" (WebSocket only)

Call

{"jsonrpc":"2.0","method":"authenticate","params":["<bearer_token>"], "id":1}

Success Response

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

How did we do?

Related Articles

• Diode App Introduction
• Diode API Curl Example (send_message)
• Updating the Diode App