type: google.api.Service
config_version: 3

http:
  rules:
    - selector: bdware.bdledger.api.Node.ClientVersion
      get: /v0/node/version
    - selector: bdware.bdledger.api.Ledger.CreateLedger
      post: /v0/ledgers
      body: "*"
    - selector: bdware.bdledger.api.Ledger.GetLedgers
      get: /v0/ledgers
    - selector: bdware.bdledger.api.Ledger.SendTransaction
      post: /v0/ledgers/{ledger}/transactions
      body: "*"
    - selector: bdware.bdledger.api.Query.GetBlockByHash
      get: /v0/ledgers/{ledger}/block
    - selector: bdware.bdledger.api.Query.GetBlocks
      post: /v0/ledgers/{ledger}/blocks/query
      body: "*"
    - selector: bdware.bdledger.api.Query.CountBlocks
      post: /v0/ledgers/{ledger}/blocks/count
      body: "*"
    - selector: bdware.bdledger.api.Query.GetRecentBlocks
      get: /v0/ledgers/{ledger}/blocks/recent
    - selector: bdware.bdledger.api.Query.GetTransactionByHash
      get: /v0/ledgers/{ledger}/transaction
    - selector: bdware.bdledger.api.Query.GetTransactionByBlockHashAndIndex
      get: /v0/ledgers/{ledger}/block/transaction
    - selector: bdware.bdledger.api.Query.GetTransactions
      post: /v0/ledgers/{ledger}/transactions/query
      body: "*"
    - selector: bdware.bdledger.api.Query.CountTransactions
      post: /v0/ledgers/{ledger}/transactions/count
      body: "*"

Note

Request/Response data of bytes type should/will be encoded with Base64.

Note

When using hash strings in URL, they need to be encoded with encodeURIComponent.

Request Examples {#_request_examples}

Node.ClientVersion {#_node_clientversion}

Get BDLedger node version

GET http://{{IP}}:{{PORT}}/v0/node/version

Response.

{
  "version": "dev-210119.a88bf4eb"
}

Ledger.CreateLedger {#_ledger_createledger}

Create a new ledger

POST http://{{IP}}:{{PORT}}/v0/ledgers

Request body.

{
  "name": "test"
}

Response.

{
  "ok": true
}

Ledger.GetLedgers {#_ledger_getledgers}

Get all ledgers

GET http://{{IP}}:{{PORT}}/v0/ledgers

Response.

{
  "ledgers": [
    "default",
    "test"
  ]
}

Ledger.SendTransaction {#_ledger_sendtransaction}

Send a new transaction

POST http://{{IP}}:{{PORT}}/v0/ledgers/test/transactions

Request body.

{
  "transaction": {
    "type": 0,
    "from": "8A3K/vANyv7wDcr+8A3K/vANyv4=",
    "nonce": 52,
    "data": "lQItWZKS5hlUn6V/DMKKwvZXxvM="
  }
}

Response.

{
  "hash": "VQBeA5Ee0Y5hqEileoQuYMHbOSE="
}

Query.GetBlockByHash {#_query_getblockbyhash}

Get a block identified by its hash

GET http://{{IP}}:{{PORT}}/v0/ledgers/test/block?hash=LSKr%2BK079Ax%2BrKdlyYN5ze2YGzo%3D

hash has to be encoded with encodeURIComponent

Response.

{
  "block": {
    "hash": "LSKr+K079Ax+rKdlyYN5ze2YGzo=",
    "creator": "",
    "nonce": "0",
    "parentHashes": [
      "fLX5pMY8M1qSAGZdKT1rWBkdEMo=",
      "rk0DWMaUpRG82yVX+cFhbfhPFdw=",
      "3XkwkuMBearq8uavN76Te7Zdpl8="
    ],
    "witnesses": [],
    "timestamp": "1611038043",
    "size": "0",
    "transactionCount": 1,
    "transactionsRoot": "VQBeA5Ee0Y5hqEileoQuYMHbOSE=",
    "transactions": [
      {
        "blockHash": "",
        "blockTimestamp": "0",
        "index": 0,
        "hash": "VQBeA5Ee0Y5hqEileoQuYMHbOSE=",
        "type": "RECORD",
        "from": "8A3K/vANyv7wDcr+8A3K/vANyv4=",
        "nonce": "0",
        "to": "AAAAAAAAAAAAAAAAAAAAAAAAAAA=",
        "data": "lQItWZKS5hlUn6V/DMKKwvZXxvM="
      }
    ],
    "transactionHashes": [
      "VQBeA5Ee0Y5hqEileoQuYMHbOSE="
    ]
  }
}

Query.GetBlocks {#_query_getblocks}

Get blocks in a timestamp range

POST http://{{IP}}:{{PORT}}/v0/ledgers/test/blocks/query

enum IncludeTransactions {
  NONE = 0; // Don't include transaction data
  HASH = 1; // Include transactions hashes
  FULL = 2; // Include full transactions
}

Requirement: asciimath:[“start_timestamp”⇐”end_timestamp”]

If only end_timestamp is not specified, or asciimath:[“end_timestamp”-“start_timestamp”>”query.maxDuration”], then end_timestamp will be set to asciimath:[“start_timestamp”+”query.maxDuration”].

If only start_timestamp is not specified, then start_timestamp will be set to asciimath:[“end_timestamp”-“query.maxDuration”].

In all cases, start_timestamp will never be earlier than the genesis block’s timestamp, and end_timestamp will never be later than the current timestamp when the node process the query request.

Request body 1.

{
  "start_timestamp": 1611038000,
  "end_timestamp": 1611039000,
  "include_transactions": 0
}

Response 1.

{
  "blocks": [
    {
      "hash": "LSKr+K079Ax+rKdlyYN5ze2YGzo=",
      "creator": "",
      "nonce": "0",
      "parentHashes": [
        "fLX5pMY8M1qSAGZdKT1rWBkdEMo=",
        "rk0DWMaUpRG82yVX+cFhbfhPFdw=",
        "3XkwkuMBearq8uavN76Te7Zdpl8="
      ],
      "witnesses": [],
      "timestamp": "1611038043",
      "size": "0",
      "transactionCount": 1,
      "transactionsRoot": "VQBeA5Ee0Y5hqEileoQuYMHbOSE=",
      "transactions": [],
      "transactionHashes": []
    }
  ],
  "startTimestamp": "1611038043",
  "endTimestamp": "1611038043"
}

Request body 2.

{
  "start_timestamp": 1611038000,
  "end_timestamp": 1611039000,
  "include_transactions": 1
}

Response 2.

{
  "blocks": [
    {
      "hash": "LSKr+K079Ax+rKdlyYN5ze2YGzo=",
      "creator": "",
      "nonce": "0",
      "parentHashes": [
        "fLX5pMY8M1qSAGZdKT1rWBkdEMo=",
        "rk0DWMaUpRG82yVX+cFhbfhPFdw=",
        "3XkwkuMBearq8uavN76Te7Zdpl8="
      ],
      "witnesses": [],
      "timestamp": "1611038043",
      "size": "0",
      "transactionCount": 1,
      "transactionsRoot": "VQBeA5Ee0Y5hqEileoQuYMHbOSE=",
      "transactions": [],
      "transactionHashes": [
        "VQBeA5Ee0Y5hqEileoQuYMHbOSE="
      ]
    }
  ],
  "startTimestamp": "1611038043",
  "endTimestamp": "1611038043"
}

Request body 3.

{
  "start_timestamp": 1611038000,
  "end_timestamp": 1611039000,
  "include_transactions": 2
}

Response 3.

{
  "blocks": [
    {
      "hash": "LSKr+K079Ax+rKdlyYN5ze2YGzo=",
      "creator": "",
      "nonce": "0",
      "parentHashes": [
        "fLX5pMY8M1qSAGZdKT1rWBkdEMo=",
        "rk0DWMaUpRG82yVX+cFhbfhPFdw=",
        "3XkwkuMBearq8uavN76Te7Zdpl8="
      ],
      "witnesses": [],
      "timestamp": "1611038043",
      "size": "0",
      "transactionCount": 1,
      "transactionsRoot": "VQBeA5Ee0Y5hqEileoQuYMHbOSE=",
      "transactions": [
        {
          "blockHash": "",
          "blockTimestamp": "0",
          "index": 0,
          "hash": "VQBeA5Ee0Y5hqEileoQuYMHbOSE=",
          "type": "RECORD",
          "from": "8A3K/vANyv7wDcr+8A3K/vANyv4=",
          "nonce": "0",
          "to": "AAAAAAAAAAAAAAAAAAAAAAAAAAA=",
          "data": "lQItWZKS5hlUn6V/DMKKwvZXxvM="
        }
      ],
      "transactionHashes": [
        "VQBeA5Ee0Y5hqEileoQuYMHbOSE="
      ]
    }
  ],
  "startTimestamp": "1611038043",
  "endTimestamp": "1611038043"
}

Query.CountBlocks {#_query_countblocks}

Count all blocks in a ledger, or blocks in a timestamp range

POST http://{{IP}}:{{PORT}}/v0/ledgers/test/blocks/count

Requirement: asciimath:[“start_timestamp”⇐”end_timestamp”]

If neither start_timestamp nor end_timestamp is specified, then count all blocks in the specified ledger.

If only end_timestamp is not specified, then count all blocks with timestamps later than start_timestamp.

If only start_timestamp is not specified, then count all blocks with timestamps earlier than end_timestamp.

In all cases, start_timestamp will never be earlier than the genesis block’s timestamp, and end_timestamp will never be later than the current timestamp when the node process the query request.

Request body 1.

{}

Response 1.

{
  "count": "5",
  "startTimestamp": "0",
  "endTimestamp": "1611039957"
}

Request body 2.

{
  "start_timestamp": 1611038000,
  "end_timestamp": 1611039000
}

Response 2.

{
  "count": "1",
  "startTimestamp": "1611038000",
  "endTimestamp": "1611039000"
}

Query.GetRecentBlocks {#_query_getrecentblocks}

Get recent count blocks (Only support IncludeTransactions=NONE for now)

GET http://{{IP}}:{{PORT}}/v0/ledgers/test/blocks/recent?count=2

Response.

{
  "blocks": [
    {
      "hash": "LSKr+K079Ax+rKdlyYN5ze2YGzo=",
      "creator": "",
      "nonce": "0",
      "parentHashes": [
        "fLX5pMY8M1qSAGZdKT1rWBkdEMo=",
        "rk0DWMaUpRG82yVX+cFhbfhPFdw=",
        "3XkwkuMBearq8uavN76Te7Zdpl8="
      ],
      "witnesses": [],
      "timestamp": "1611038043",
      "size": "0",
      "transactionCount": 1,
      "transactionsRoot": "VQBeA5Ee0Y5hqEileoQuYMHbOSE=",
      "transactions": [],
      "transactionHashes": []
    },
    {
      "hash": "rk0DWMaUpRG82yVX+cFhbfhPFdw=",
      "creator": "",
      "nonce": "0",
      "parentHashes": [
        "fLX5pMY8M1qSAGZdKT1rWBkdEMo=",
        "3XkwkuMBearq8uavN76Te7Zdpl8=",
        "8pZPR74OALIbps5XFb4dL/s0j0M="
      ],
      "witnesses": [],
      "timestamp": "1610968019",
      "size": "0",
      "transactionCount": 1,
      "transactionsRoot": "LuxttCm/pSHVMOKF0sJExk+DJXc=",
      "transactions": [],
      "transactionHashes": []
    }
  ],
  "startTimestamp": "1610968019",
  "endTimestamp": "1611038043"
}

Query.GetTransactionByHash {#_query_gettransactionbyhash}

Get a transaction identified by its hash

GET http://{{IP}}:{{PORT}}/v0/ledgers/test/transaction?hash=VQBeA5Ee0Y5hqEileoQuYMHbOSE%3D

hash has to be encoded with encodeURIComponent

Response.

{
  "transaction": {
    "blockHash": "LSKr+K079Ax+rKdlyYN5ze2YGzo=",
    "blockTimestamp": "1611038043",
    "index": 0,
    "hash": "VQBeA5Ee0Y5hqEileoQuYMHbOSE=",
    "type": "RECORD",
    "from": "8A3K/vANyv7wDcr+8A3K/vANyv4=",
    "nonce": "0",
    "to": "AAAAAAAAAAAAAAAAAAAAAAAAAAA=",
    "data": "lQItWZKS5hlUn6V/DMKKwvZXxvM="
  }
}

Query.GetTransactionByBlockHashAndIndex {#_query_gettransactionbyblockhashandindex}

Get a transaction identified by hash of the block it belongs to and its index inside the block

GET http://{{IP}}:{{PORT}}/v0/ledgers/test/block/transaction?blockHash=LSKr%2BK079Ax%2BrKdlyYN5ze2YGzo%3D&index=0

blockHash has to be encoded with encodeURIComponent

Response.

{
  "transaction": {
    "blockHash": "LSKr+K079Ax+rKdlyYN5ze2YGzo=",
    "blockTimestamp": "1611038043",
    "index": 0,
    "hash": "VQBeA5Ee0Y5hqEileoQuYMHbOSE=",
    "type": "RECORD",
    "from": "8A3K/vANyv7wDcr+8A3K/vANyv4=",
    "nonce": "0",
    "to": "AAAAAAAAAAAAAAAAAAAAAAAAAAA=",
    "data": "lQItWZKS5hlUn6V/DMKKwvZXxvM="
  }
}

Query.GetTransactions {#_query_gettransactions}

Get transactions in a timestamp range

POST http://{{IP}}:{{PORT}}/v0/ledgers/test/transactions/query

start_timestamp and end_timestamp follow the same requirements and rules as in ???.

Request body.

{
  "start_timestamp": 1611038000,
  "end_timestamp": 1611039000
}

Response.

{
  "transactions": [
    {
      "blockHash": "",
      "blockTimestamp": "0",
      "index": 0,
      "hash": "VQBeA5Ee0Y5hqEileoQuYMHbOSE=",
      "type": "RECORD",
      "from": "8A3K/vANyv7wDcr+8A3K/vANyv4=",
      "nonce": "0",
      "to": "AAAAAAAAAAAAAAAAAAAAAAAAAAA=",
      "data": "lQItWZKS5hlUn6V/DMKKwvZXxvM="
    }
  ],
  "startTimestamp": "1611038043",
  "endTimestamp": "1611038043"
}

Query.CountTransactions {#_query_counttransactions}

Count all transactions in a ledger, or transactions in a timestamp range

POST http://{{IP}}:{{PORT}}/v0/ledgers/test/transactions/count

start_timestamp and end_timestamp follow the same requirements and rules as in ???.

Request body 1.

{}

Response 1.

{
  "count": "4",
  "startTimestamp": "0",
  "endTimestamp": "1611039957"
}

Request body 2.

{
  "start_timestamp": 1611038000,
  "end_timestamp": 1611039000
}

Response 2.

{
  "count": "1",
  "startTimestamp": "1611038000",
  "endTimestamp": "1611039000"
}