Skip to content

Latest commit

 

History

History
1054 lines (780 loc) · 46.3 KB

maintenance-api.md

File metadata and controls

1054 lines (780 loc) · 46.3 KB
Raw

Maintenance API

Node Management API v0.1.0

Scroll down for example requests and responses.

goloop management

Base URLs:

node

Node Management

View system

Code samples

GET /system

Return system information.

Parameters

Name In Type Required Description
format query string false Format the output using the given Go template

Example responses

200 Response

{
  "buildVersion": "v0.1.7",
  "buildTags": "linux/amd64 tags()-2019-08-20-09:39:15",
  "setting": {
    "address": "hx4208599c8f58fed475db747504a80a311a3af63b",
    "p2p": "localhost:8080",
    "p2pListen": "localhost:8080",
    "rpcAddr": ":9080",
    "rpcDump": false
  },
  "config": {
    "eeInstances": 1,
    "rpcDefaultChannel": "",
    "rpcIncludeDebug": false
  }
}

Responses

Status Meaning Description Schema
200 OK Success System
500 Internal Server Error Internal Server Error None

This operation does not require authentication

View system configuration

Code samples

GET /system/configure

Return system configuration.

Example responses

200 Response

{
  "eeInstances": 1,
  "rpcDefaultChannel": "",
  "rpcIncludeDebug": false
}

Responses

Status Meaning Description Schema
200 OK Success SystemConfig
500 Internal Server Error Internal Server Error None

This operation does not require authentication

Configure system

Code samples

POST /system/configure

Configure system, configurable properties refer to SystemConfig

Body parameter

{
  "key": "string",
  "value": "string"
}

Parameters

Name In Type Required Description
body body ConfigureParam true key-value to configure

Responses

Status Meaning Description Schema
200 OK Success None
500 Internal Server Error Internal Server Error None

This operation does not require authentication

List Backups

Code samples

GET /system/backup

Return list of backups

Example responses

200 Response

[
  {
    "name": "0x178977_0x1_1_20200715-111057.zip",
    "cid": "0x178977",
    "nid": "0x1",
    "channel": "1",
    "height": 2021,
    "codec": "rlp"
  }
]

Responses

Status Meaning Description Schema
200 OK Success BackupList
500 Internal Server Error Internal Server Error None

This operation does not require authentication

Restore Status

Code samples

GET /system/restore

View the status of restoring

Example responses

200 Response

{
  "name": "0x178977_0x1_1_20200715-111057.zip",
  "overwrite": true,
  "state": "started 23/128"
}

Responses

Status Meaning Description Schema
200 OK Success RestoreStatus
500 Internal Server Error Internal Server Error None

This operation does not require authentication

Start Restore

Code samples

POST /system/restore

Start to restore chain from the backup

Body parameter

{
  "name": "0x178977_0x1_1_20200715-111057.zip",
  "overwrite": true
}

Parameters

Name In Type Required Description
body body RestoreParam true Name of backup and options

Responses

Status Meaning Description Schema
200 OK Success None
500 Internal Server Error Internal Server Error None

This operation does not require authentication

Stop Restore

Code samples

DELETE /system/restore

Stop restoring operation

Responses

Status Meaning Description Schema
200 OK Success None
500 Internal Server Error Internal Server Error None

This operation does not require authentication

chain

Chain Management

List Chains

Code samples

GET /chain

Returns a list of chains

Example responses

200 Response

[
  {
    "cid": "0x782b03",
    "nid": "0x000000",
    "channel": "000000",
    "state": "started",
    "height": 100,
    "lastError": ""
  }
]

Responses

Status Meaning Description Schema
200 OK Success Inline
500 Internal Server Error Internal Server Error None

Response Schema

Status Code 200

array of chains

Name Type Required Restrictions Description
anonymous [Chain] false none array of chains
» cid string("0x" + lowercase HEX string) false none chain-id of chain
» nid string("0x" + lowercase HEX string) false none network-id of chain
» channel string false none chain-alias of node
» height integer(int64) false none block height of chain
» state string false none state of chain
» lastError string false none last error of chain

This operation does not require authentication

Join Chain

Code samples

POST /chain

Join Chain

Body parameter

json:
  dbType: goleveldb
  seedAddress: 'localhost:8080'
  role: 3
  concurrencyLevel: 1
  normalTxPool: 5000
  patchTxPool: 1000
  maxBlockTxBytes: 1048576
  nodeCache: none
  channel: '000000'
  secureSuites: 'none,tls,ecdhe'
  secureAeads: 'chacha,aes128,aes256'
  defaultWaitTimeout: 0
  txTimeout: 0
  maxWaitTimeout: 0
  autoStart: false
genesisZip: string

Parameters

Name In Type Required Description
body body object true Genesis-Storage zip file and json encoded chain-configuration for join chain using multipart
» json body ChainConfig true json encoded chain-configuration, using multipart 'Content-Disposition: name=json'
»» dbType body string false Name of database system, ReadOnly
»» seedAddress body string false List of Seed ip-port, Comma separated string, Runtime-Configurable
»» role body integer false Role:
»» concurrencyLevel body integer false Maximum number of executors to use for concurrency
»» normalTxPool body integer false Size of normal transaction pool
»» patchTxPool body integer false Size of patch transaction pool
»» maxBlockTxBytes body integer false Max size of transactions in a block
»» nodeCache body string false Node cache:
»» channel body string false Chain-alias of node
»» secureSuites body string false Supported Secure suites with order (none,tls,ecdhe) - Comma separated string
»» secureAeads body string false Supported Secure AEAD with order (chacha,aes128,aes256) - Comma separated string
»» defaultWaitTimeout body integer false Default wait timeout in milli-second(0:disable)
»» maxWaitTimeout body integer false Max wait timeout in milli-second(0:uses same value of defaultWaitTimeout)
»» txTimeout body integer false Transaction timeout in milli-second(0:uses system default value)
»» autoStart body boolean false Start the chain automatically on node start
» genesisZip body string(binary) true Genesis-Storage zip file, using multipart 'Content-Disposition: name=genesisZip'

Detailed descriptions

»» role: Role:

  • 0 - None

  • 1 - Seed

  • 2 - Validator

  • 3 - Seed and Validator

    Runtime-Configurable

»» nodeCache: Node cache:

  • none - No cache
  • small - Memory Lv1 ~ Lv5 for all
  • large - Memory Lv1 ~ Lv5 for all and File Lv6 for store

Enumerated Values

Parameter Value
»» dbType badgerdb
»» dbType goleveldb
»» dbType boltdb
»» dbType mapdb
»» role 0
»» role 1
»» role 2
»» role 3
»» nodeCache none
»» nodeCache small
»» nodeCache large

Example responses

200 Response

Responses

Status Meaning Description Schema
200 OK Success ChainID
409 Conflict Conflict None
500 Internal Server Error Internal Server Error None

This operation does not require authentication

Inspect Chain

Code samples

GET /chain/{cid}

Return low-level information about a chain.

Parameters

Name In Type Required Description
cid path string("0x" + lowercase HEX string) true chain-id of chain
format query string false Format the output using the given Go template
informal query boolean false Inspect with informal data

Example responses

200 Response

{
  "cid": "0x782b03",
  "nid": "0x000000",
  "channel": "000000",
  "state": "started",
  "height": 100,
  "lastError": "",
  "genesisTx": {},
  "config": {
    "dbType": "goleveldb",
    "seedAddress": "localhost:8080",
    "role": 3,
    "concurrencyLevel": 1,
    "normalTxPool": 5000,
    "patchTxPool": 1000,
    "maxBlockTxBytes": 1048576,
    "nodeCache": "none",
    "channel": "000000",
    "secureSuites": "none,tls,ecdhe",
    "secureAeads": "chacha,aes128,aes256",
    "defaultWaitTimeout": 0,
    "txTimeout": 0,
    "maxWaitTimeout": 0,
    "autoStart": false
  },
  "module": {
    "property1": {},
    "property2": {}
  }
}

Responses

Status Meaning Description Schema
200 OK Success ChainInspect
404 Not Found Not Found None
500 Internal Server Error Internal Server Error None

This operation does not require authentication

Leave Chain

Code samples

DELETE /chain/{cid}

Leave Chain.

Parameters

Name In Type Required Description
cid path string("0x" + lowercase HEX string) true chain-id of chain

Responses

Status Meaning Description Schema
200 OK Success None
404 Not Found Not Found None
500 Internal Server Error Internal Server Error None

This operation does not require authentication

Start Chain

Code samples

POST /chain/{cid}/start

Start Chain.

Parameters

Name In Type Required Description
cid path string("0x" + lowercase HEX string) true chain-id of chain

Responses

Status Meaning Description Schema
200 OK Success None
404 Not Found Not Found None
500 Internal Server Error Internal Server Error None

This operation does not require authentication

Stop Chain

Code samples

POST /chain/{cid}/stop

Stop Chain.

Parameters

Name In Type Required Description
cid path string("0x" + lowercase HEX string) true chain-id of chain

Responses

Status Meaning Description Schema
200 OK Success None
404 Not Found Not Found None
500 Internal Server Error Internal Server Error None

This operation does not require authentication

Reset Chain

Code samples

POST /chain/{cid}/reset

Reset Chain.

Parameters

Name In Type Required Description
cid path string("0x" + lowercase HEX string) true chain-id of chain

Responses

Status Meaning Description Schema
200 OK Success None
404 Not Found Not Found None
500 Internal Server Error Internal Server Error None

This operation does not require authentication

Import Chain

Code samples

POST /chain/{cid}/import

Import a chain from legacy database.

Body parameter

{
  "dbPath": "/path/to/database",
  "height": 1
}

Parameters

Name In Type Required Description
cid path string("0x" + lowercase HEX string) true chain-id of chain
body body ChainImportParam true none

Responses

Status Meaning Description Schema
200 OK Success None
404 Not Found Not Found None
500 Internal Server Error Internal Server Error None

This operation does not require authentication

Prune Chain

Code samples

POST /chain/{cid}/prune

Prune chain data from the specific height

Body parameter

{
  "dbType": "goleveldb",
  "height": 1
}

Parameters

Name In Type Required Description
cid path string("0x" + lowercase HEX string) true chain-id of chain
body body PruneParam true none

Responses

Status Meaning Description Schema
200 OK Success None
404 Not Found Not Found None
500 Internal Server Error Internal Server Error None

This operation does not require authentication

Backup Chain

Code samples

POST /chain/{cid}/backup

Backup chain data to the specific file

Parameters

Name In Type Required Description
cid path string("0x" + lowercase HEX string) true chain-id of chain

Responses

Status Meaning Description Schema
200 OK Success None
404 Not Found Not Found None
500 Internal Server Error Internal Server Error None

This operation does not require authentication

Download Genesis-Storage

Code samples

GET /chain/{cid}/genesis

Download Genesis-Storage zip file

Parameters

Name In Type Required Description
cid path string("0x" + lowercase HEX string) true chain-id of chain

Example responses

200 Response

Responses

Status Meaning Description Schema
200 OK Success string
404 Not Found Not Found None
500 Internal Server Error Internal Server Error None

This operation does not require authentication

View chain configuration

Code samples

GET /chain/{cid}/configure

Return chain configuration.

Parameters

Name In Type Required Description
cid path string("0x" + lowercase HEX string) true chain-id of chain

Example responses

200 Response

{
  "dbType": "goleveldb",
  "seedAddress": "localhost:8080",
  "role": 3,
  "concurrencyLevel": 1,
  "normalTxPool": 5000,
  "patchTxPool": 1000,
  "maxBlockTxBytes": 1048576,
  "nodeCache": "none",
  "channel": "000000",
  "secureSuites": "none,tls,ecdhe",
  "secureAeads": "chacha,aes128,aes256",
  "defaultWaitTimeout": 0,
  "txTimeout": 0,
  "maxWaitTimeout": 0,
  "autoStart": false
}

Responses

Status Meaning Description Schema
200 OK Success ChainConfig
404 Not Found Not Found None
500 Internal Server Error Internal Server Error None

This operation does not require authentication

Configure chain

Code samples

POST /chain/{cid}/configure

Configure chain, configurable properties refer to ChainConfig

Body parameter

{
  "key": "string",
  "value": "string"
}

Parameters

Name In Type Required Description
cid path string("0x" + lowercase HEX string) true chain-id of chain
body body ConfigureParam true key-value to configure

Responses

Status Meaning Description Schema
200 OK Success None
404 Not Found Not Found None
500 Internal Server Error Internal Server Error None

This operation does not require authentication

Schemas

ChainID 

"0x782b03"

chain-id of chain, "0x" + lowercase HEX string

Properties

Name Type Required Restrictions Description
anonymous string false none chain-id of chain, "0x" + lowercase HEX string

Chain 

{
  "cid": "0x782b03",
  "nid": "0x000000",
  "channel": "000000",
  "state": "started",
  "height": 100,
  "lastError": ""
}

Properties

Name Type Required Restrictions Description
cid string("0x" + lowercase HEX string) false none chain-id of chain
nid string("0x" + lowercase HEX string) false none network-id of chain
channel string false none chain-alias of node
height integer(int64) false none block height of chain
state string false none state of chain
lastError string false none last error of chain

ChainInspect 

{
  "cid": "0x782b03",
  "nid": "0x000000",
  "channel": "000000",
  "state": "started",
  "height": 100,
  "lastError": "",
  "genesisTx": {},
  "config": {
    "dbType": "goleveldb",
    "seedAddress": "localhost:8080",
    "role": 3,
    "concurrencyLevel": 1,
    "normalTxPool": 5000,
    "patchTxPool": 1000,
    "maxBlockTxBytes": 1048576,
    "nodeCache": "none",
    "channel": "000000",
    "secureSuites": "none,tls,ecdhe",
    "secureAeads": "chacha,aes128,aes256",
    "defaultWaitTimeout": 0,
    "txTimeout": 0,
    "maxWaitTimeout": 0,
    "autoStart": false
  },
  "module": {
    "property1": {},
    "property2": {}
  }
}

Properties

allOf

Name Type Required Restrictions Description
anonymous Chain false none none

and

Name Type Required Restrictions Description
anonymous object false none none
» genesisTx object false none Genesis Transaction
» config ChainConfig false none none
» module object false none none
»» additionalProperties object false none none

ChainConfig 

{
  "dbType": "goleveldb",
  "seedAddress": "localhost:8080",
  "role": 3,
  "concurrencyLevel": 1,
  "normalTxPool": 5000,
  "patchTxPool": 1000,
  "maxBlockTxBytes": 1048576,
  "nodeCache": "none",
  "channel": "000000",
  "secureSuites": "none,tls,ecdhe",
  "secureAeads": "chacha,aes128,aes256",
  "defaultWaitTimeout": 0,
  "txTimeout": 0,
  "maxWaitTimeout": 0,
  "autoStart": false
}

Properties

Name Type Required Restrictions Description
dbType string false none Name of database system, ReadOnly
seedAddress string false none List of Seed ip-port, Comma separated string, Runtime-Configurable
role integer false none Role: _ 0 - None _ 1 - Seed _ 2 - Validator _ 3 - Seed and Validator Runtime-Configurable
concurrencyLevel integer false none Maximum number of executors to use for concurrency
normalTxPool integer false none Size of normal transaction pool
patchTxPool integer false none Size of patch transaction pool
maxBlockTxBytes integer false none Max size of transactions in a block
nodeCache string false none Node cache: _ none - No cache _ small - Memory Lv1 ~ Lv5 for all * large - Memory Lv1 ~ Lv5 for all and File Lv6 for store
channel string false none Chain-alias of node
secureSuites string false none Supported Secure suites with order (none,tls,ecdhe) - Comma separated string
secureAeads string false none Supported Secure AEAD with order (chacha,aes128,aes256) - Comma separated string
defaultWaitTimeout integer false none Default wait timeout in milli-second(0:disable)
maxWaitTimeout integer false none Max wait timeout in milli-second(0:uses same value of defaultWaitTimeout)
txTimeout integer false none Transaction timeout in milli-second(0:uses system default value)
autoStart boolean false none Start the chain automatically on node start

Enumerated Values

Property Value
dbType badgerdb
dbType goleveldb
dbType boltdb
dbType mapdb
role 0
role 1
role 2
role 3
nodeCache none
nodeCache small
nodeCache large

ChainImportParam 

{
  "dbPath": "/path/to/database",
  "height": 1
}

Properties

Name Type Required Restrictions Description
dbPath string true none Database path
height int64 true none Block Height

System 

{
  "buildVersion": "v0.1.7",
  "buildTags": "linux/amd64 tags()-2019-08-20-09:39:15",
  "setting": {
    "address": "hx4208599c8f58fed475db747504a80a311a3af63b",
    "p2p": "localhost:8080",
    "p2pListen": "localhost:8080",
    "rpcAddr": ":9080",
    "rpcDump": false
  },
  "config": {
    "eeInstances": 1,
    "rpcDefaultChannel": "",
    "rpcIncludeDebug": false
  }
}

Properties

Name Type Required Restrictions Description
buildVersion string false none build version
buildTags string false none buildTags
setting object false none none
» address string false none wallet address
» p2p string false none p2p address
» p2pListen string false none p2p listen address
» rpcAddr string false none Listen ip-port of JSON-RPC
» rpcDump boolean false none JSON-RPC Request, Response Dump flag
config SystemConfig false none none

SystemConfig 

{
  "eeInstances": 1,
  "rpcDefaultChannel": "",
  "rpcIncludeDebug": false
}

Properties

Name Type Required Restrictions Description
eeInstances integer false none eeInstances
rpcDefaultChannel string false none default channel for legacy api
rpcIncludeDebug boolean false none JSON-RPC Response with detail information

ConfigureParam 

{
  "key": "string",
  "value": "string"
}

Properties

Name Type Required Restrictions Description
key string true none configuration field name
value string true none configuration value

PruneParam 

{
  "dbType": "goleveldb",
  "height": 1
}

Properties

Name Type Required Restrictions Description
dbType string false none Database type
height int64 true none Block Height

BackupList 

[
  {
    "name": "0x178977_0x1_1_20200715-111057.zip",
    "cid": "0x178977",
    "nid": "0x1",
    "channel": "1",
    "height": 2021,
    "codec": "rlp"
  }
]

Properties

None

RestoreStatus 

{
  "name": "0x178977_0x1_1_20200715-111057.zip",
  "overwrite": true,
  "state": "started 23/128"
}

Properties

Name Type Required Restrictions Description
state string true none State of the job (stopped, started N/T, stopping, failed, success)
name string false none Name of backup
overwrite boolean false none Whether it replaces existing chain data

RestoreParam 

{
  "name": "0x178977_0x1_1_20200715-111057.zip",
  "overwrite": true
}

Properties

Name Type Required Restrictions Description
name string true none Name of the backup to restore
overwrite boolean false none Whether it replaces existing chain