REST

Overview

The Node API endpoints attempt to conform to the design principles of Representational State Transfer (REST). Radix Node APIs use the JSON data format for responses and requests.

Request

Methods to retrieve data from the REST API require a GET request. Methods that submit or modify data require a POST request. A DELETE request is also accepted for methods that destroy data.

Note: API methods will return an error if not invoked using the correct verb.

Successful response

The REST API sends specific HTTP status codes in response to API requests. For successful responses, the standard 200 response code is used. Any other data returned in response is provided as a well-formed JSON object in the body of the response.

Error response

In the event of a problem, the status code will contain an error code, while the body of the response will usually contain additional information about the problem that was encountered.

Refer to the Response codes page for detailed information.

API methods

(GET) Get Live Peers

This method allows you to get the Node's live Peers. Live peers are nodes which are still seen to be connected to the network.

Request
Response

Endpoint

https://[node IP]/api/network/peers/live

Example call

curl -g -k https://betanet-demo.radixnode.net/api/network/peers/live

(GET) Get Network

This method allows you to get the Node's Network details.

Request
Response

Endpoint

https://[node IP]/api/network

Example call

curl -g -k https://betanet-demo.radixnode.net/api/network

(GET) Get Peers

This method allows you to get all the Peers known by the Node.

Request
Response

Endpoint

https://[node IP]/api/network/peers

Example call

curl -g -k https://betanet-demo.radixnode.net/api/network/peers

(GET) Get System

This endpoint allows you to get the Node's System details.

Request
Response

Endpoint

https://[node IP]/api/system

Example call

curl -g -k https://betanet-demo.radixnode.net/api/system
{
"agent": {
"name": ":str:/Radix:/2700000",
"protocol": 100,
"version": 2700000
},
"clock": 604,
"commitment": ":hsh:c163067c287f46f7119c644a35c8e0e3ae0c8d1c112f2a02e531e8ea0b65596b",
"events": {
"broadcast": 962730,
"dequeued": 40859,
"processed": {
"asynchronous": 40859,
"synchronous": 39781
},
"processing": 0,
"queued": 40859
},
"hid": ":uid:565f9d83e478dcbf527487e5267b599c",
"key": ":byt:AxG+dTmjmfRtIV1n3Quy72M8QlEeTp78L74qgoGAkFIx",
"ledger": {
"checksum": 4862339469912619842,
"faults": {
"assists": 0,
"failed": 0,
"stitched": 0,
"tears": 0
},
"latency": {
"path": 0,
"persist": 0
},
"processed": 604,
"processing": 0,
"stored": 604,
"storing": 0
},
"memory": {
"free": 51177920,
"max": 5519704064,
"total": 212336640
},
"messages": {
"inbound": {
"discarded": 0,
"pending": 0,
"processed": 609398,
"received": 609402
},
"outbound": {
"aborted": 2,
"pending": 0,
"processed": 312346,
"sent": 312348
}
},
"nid": ":uid:df9e7ad3981668cb6cbf70c2b0a77431",
"planck": 25852923,
"port": 30000,
"processors": 2,
"serializer": 195914042,
"shards": {
"high": 9223372036854775807,
"low": -9223372036854775808
},
"version": 100
}

(GET) Get Universe

This endpoint allows you to get the Node's current Universe.

Request
Response

Endpoint

https://[node IP]/api/universe

Example call

curl -g -k https://betanet-demo.radixnode.net/api/universe

(GET) Ping

This method allows you to ping the Node.

Request
Response

Endpoint

https://[node IP]/api/ping

Example call

curl -g -k https://betanet-demo.radixnode.net/api/ping
{
"response": "pong",
"timestamp": 123456
}

Restricted access methods

The following REST API methods require user access credentials. For details on the authorization method used by the API, please review the Authentication section.

Authentication

The Radix Node API uses basic HTTP authentication. The request must contain a header field of the form Authorization: Basic <credentials>, where credentials is the base64 encoding of the username and password joined by a colon.

For example, if the Node uses Aladdin as the username and OpenSesame as the password, then the field's value is the base64-encoding of Aladdin:OpenSesame, or QWxhZGRpbjpPcGVuU2VzYW1l. The Authorization header will appear as:

Authorization: Basic QWxhZGRpbjpPcGVuU2VzYW1l

A client may avoid a login prompt when accessing a basic access authentication by prepending username:password@ to the hostname in the URL. For example:

https://Aladdin:OpenSesame@127.0.0.1/rpc

(GET) Get Mass

This endpoint allows you to get the Node's Mass.

Request
Response

Endpoint

https://[node IP]/api/graph/node/mass

Headers

Header

Value

Authorization: Basic

Access credentials

Example call

curl -g -k https://user:password@betanet-demo.radixnode.net/api/graph/node/mass
[
{
"hid": {
"serializer": "EUID",
"value": "3288409733777480474805504553"
},
"interval": 2147483647,
"mass": 4993140,
"nid": {
"serializer": "EUID",
"value": "181785696165533602980970772"
},
"serializer": 1906430966,
"version": 100
}
]

(GET) Get Modules

This endpoint allows you to get the Node's system Modules.

Request
Response

Endpoint

https://[node IP]/api/system/modules

Headers

Header

Value

Authorization: Basic

Access credentials

Example call

curl -g -k https://user:password@betanet-demo.radixnode.net/api/system/modules
[
{
"name": "Transactions",
"uid": -4798182755812596938
},
{
"name": "Mass",
"uid": -3751766842962204543
},
{
"name": "Assets",
"uid": -1063643522687655976
},
{
"name": "Profiles",
"uid": -7201039613133670975
},
{
"name": "Loggables",
"uid": -7319125975081834995
},
{
"name": "Communications",
"uid": -2101958166948269089
},
{
"name": "Atoms",
"uid": -4103723604275082673
},
{
"name": "org.radix.Radix",
"uid": -7242384034217984932
},
{
"name": "Discovery",
"uid": -1170798242368744658
}
]

(DELETE) Close Websockets

This endpoint allows you to close any currently open Websocket.

Request
Response

Endpoint

https://[node IP]/api/system/modules/api/websockets

Headers

Header

Value

Authorization: Basic

Access credentials

Example call

curl -X DELETE -k https://user:password@betanet-demo.radixnode.net/api/system/modules/api/websockets