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