# General API
The general APIs are used by the client in order to get node, block & transaction information and also, to write transaction to Miyabi blockchain ledger.
# Get Node Information
Returns general information on the current node.
# Request
- Method: GET
- URL: /getinfo
- Query parameters in URL: None
# Response
- Success:
Code: 200
Return value:
{ "value": { "name": "Nickname of the node, defaults to `identity`", "version": "Provides version information about the Miyabi library", "status": "Current status reported by the node", "starttime": "Time at which node was started", "height": "Current block height of the node", "mempoolSize": "Number of entries in the memory pool", "identity": "The node's consensus address", "networkIdentity": "The node's network address", "role": "Type of node 'Consensus/Application' node", "connections": [{ "networkIdentity": "Network identity/credential of the peer node", "endpoint": "Endpoint of the peer node", "configured": "'true' if the peer node is configured in the 'nodeconfig'", "status": "'Connected' if the current node has any connection with peer node else 'Disconnected'", }], "dbStats": "No of writes, keys, commit groups and writes per commit group", "extensions": [<List of Loaded Modules>] }, "atHeight": "Current block height at the time of response" }
# Get Block Limit
Returns the information of the maximum transaction size and maximum transaction entries per transaction.
# Request
- Method: GET
- URL: /blocklimit
- Query parameters in URL:
# Response
Success
Code: 200
Return value:
{ "value": { "MaxTransactionByteSize":"The maximum size of each transaction", "MaxEntriesPerTransaction":"Total number of entries per transaction", }, "atHeight": "Current block height at the time of response" }
Validation Error
- Code: 400
- Reason:
- Validation error or invalid height
# Get Tables
Returns a list of table descriptors of all the existing tables. Each table descriptor can have its own set of fields as per the type of descriptor.
# Request
- Method: GET
- URL: /tables
- Query parameters in URL: None
# Response
- Success
Code: 200
Return value:
{ "value": [ { "name": "Name of the table", "tracked": "Option for tracking the history of the table", "supportProofs": "Option to determine if the table allows to check for 'Proofs' or not", "type": "Name of the table type" } ], "atHeight": "Current block height at the time of response" }
# Get Height
Returns the blockchain's current height stored by the node.
# Request
- Method: GET
- URL: /height
- Query Parameters in URL: None
# Response
- Success
Code: 200
Return value:
{ "value": "Current block height of the node", "atHeight": "Current block height at the time of response" }
# Get Blocks by Height and Depth
Returns the information from a given set of blocks, which are arranged in decreasing order according to its height.
# Request
- Method: GET
- URL: /blocks
- Query Parameters in URL: Start Height, Depth
# Response
Success
Code: 200
Return value:
{ "value": [ { "txCount": "The number of transactions in the block", "sizeBytes": "The size of this block", "body": { // The block body of this block "transactions": [], "transactionResults": [], "events": { "transactionEvents": [], "filterData": "filterdata" } }, "height": "Block height", "id": "Block Id", "header": { // The header of this block "previousBlock": "Hash of previous block", "transactionsMerkleRoot": "Transactions merkle root hash", "eventsMerkleRoot": "Events merkle root hash", "stateHash": "State hash", "eventFilter": "Data representing an accumulated event filter data", "timestamp": "Data time of creation" }, "evidence": { // The signatures of this block from consensus nodes "acceptStatement": { "height": "Consensus height", "round": "Consensus round", "proposalDigest": "Evidence for consensus on a block." }, "evidence": [ <List of block evidence> ] } } ], "atHeight": "Current block height at the time of response" }
Validation Error
- Code: 400
- Reason:
- Start Height or Depth is negative
- Depth is larger than maxBlockDepth
Object Not Found
- Code: 404
- Reason:
- Start Height is larger than current height
Internal Server Error
- Code: 500
- Reason:
- Internal error
# Get Block by Block Id
Returns the block information from a given block id.
# Request
- Method: GET
- URL: /blocks/id/{id}
- Query parameters in URL: None
# Response
Success
Code: 200
Return value:
{ "value": { "txCount": "The number of transactions in the block", "sizeBytes": "The size of this block", "body": { // The block body of this block "transactions": [], "transactionResults": [], "events": { "transactionEvents": [], "filterData": "filterdata" } }, "height": "Block height", "id": "Block Id", "header": { // The header of this block "previousBlock": "Hash of previous block", "transactionsMerkleRoot": "Transactions merkle root hash", "eventsMerkleRoot": "Events merkle root hash", "stateHash": "State hash", "eventFilter": "Data representing an accumulated event filter data", "timestamp": "Data time of creation" }, "evidence": { // The signatures of this block from consensus nodes "acceptStatement": { "height": "Consensus height", "round": "Consensus round", "proposalDigest": "Evidence for consensus on a block." }, "evidence": [ <List of block evidence> ] } }, "atHeight": "Current block height at the time of response" }
Validation Error
- Code: 400
- Reason:
- Id is not a valid ByteString
Object Not Found
- Code: 404
- Reason:
- Block does not exist
# Get Block by Height
Returns the block information from a given height.
# Request
- Method: GET
- URL: /blocks/height/{blockHeight}
- Query parameters in URL: None
# Response
Success
Code: 200
Return value:
{ "value": { "txCount": "The number of transactions in the block", "sizeBytes": "The size of this block", "body": { // The block body of this block "transactions": [], "transactionResults": [], "events": { "transactionEvents": [], "filterData": "filterdata" } }, "height": "Block height", "id": "Block Id", "header": { // The header of this block "previousBlock": "Hash of previous block", "transactionsMerkleRoot": "Transactions merkle root hash", "eventsMerkleRoot": "Events merkle root hash", "stateHash": "State hash", "eventFilter": "Data representing an accumulated event filter data", "timestamp": "Data time of creation" }, "evidence": { // The signatures of this block from consensus nodes "acceptStatement": { "height": "Consensus height", "round": "Consensus round", "proposalDigest": "Evidence for consensus on a block." }, "evidence": [ <List of block evidence> ] } }, "atHeight": "Current block height at the time of response" }
Validation Error
- Code: 400
- Reason:
- Height is Invalid
Object Not Found
- Code: 404
- Reason:
- Block does not exist
# Get Block Headers by Height and Depth
Returns the header and consensus evidence from a given set of blocks, which is arranged in decreasing order according to its block height.
# Request
- Method: GET
- URL: /headers
- Query parameters in URL: Start Height, Depth
# Response
Success
Code: 200
Return value:
{ "value": [ { "height": "Block height", "id": "Block Id", "header": { // The header of this block "previousBlock": "Hash of previous block", "transactionsMerkleRoot": "Transactions merkle root hash", "eventsMerkleRoot": "Events merkle root hash", "stateHash": "State hash", "eventFilter": "Data representing an accumulated event filter data", "timestamp": "Data time of creation" }, "evidence": { // The signatures of this block from consensus nodes "acceptStatement": { "height": "Consensus height", "round": "Consensus round", "proposalDigest": "Evidence for consensus on a block." }, "evidence": [ <List of block evidence> ] } } ], "atHeight": "Current block height at the time of response" }
Validation Error
- Code: 400
- Reason:
- Start Height or Depth is negative
- Depth is larger than maxBlockDepth
Object Not Found
- Code: 404
- Reason:
- Start Height is larger than current height
Internal Server Error
- Code: 500
- Reason:
- Internal error
# Get Header by Block Id
Returns the block header and consensus evidence from a given block id.
# Request
- Method: GET
- URL: /headers/id/{id}
- Query parameters in URL: None
# Response
Success
Code: 200
Return value:
{ "value": { "height": "Block height", "id": "Block Id", "header": { // The header of this block "previousBlock": "Hash of previous block", "transactionsMerkleRoot": "Transactions merkle root hash", "eventsMerkleRoot": "Events merkle root hash", "stateHash": "State hash", "eventFilter": "Data representing an accumulated event filter data", "timestamp": "Data time of creation" }, "evidence": { // The signatures of this block from consensus nodes "acceptStatement": { "height": "Consensus height", "round": "Consensus round", "proposalDigest": "Evidence for consensus on a block." }, "evidence": [ <List of block evidence> ] } }, "atHeight": "Current block height at the time of response" }
Validation Error
- Code: 400
- Reason:
- Id is not a valid ByteString
Object Not Found
- Code: 404
- Reason:
- Block does not exist
# Get Header by Height
Returns the block header and consensus evidence from a given block height.
# Request
- Method: GET
- URL: /headers/height/{blockHeight}
- Query parameters in URL: None
# Response
Success
Code: 200
Return value:
{ "value": { "height": "Block height", "id": "Block Id", "header": { // The header of this block "previousBlock": "Hash of previous block", "transactionsMerkleRoot": "Transactions merkle root hash", "eventsMerkleRoot": "Events merkle root hash", "stateHash": "State hash", "eventFilter": "Data representing an accumulated event filter data", "timestamp": "Data time of creation" }, "evidence": { // The signatures of this block from consensus nodes "acceptStatement": { "height": "Consensus height", "round": "Consensus round", "proposalDigest": "Evidence for consensus on a block." }, "evidence": [ <List of block evidence> ] } }, "atHeight": "Current block height at the time of response" }
Validation Error
- Code: 400
- Reason:
- Height is not an integer
Object Not Found
- Code: 404
- Reason:
- Block does not exist
# Get Block Events by Block Id
Returns the block events for a given block id.
# Request
- Method: GET
- URL: /blockevents/id/{id}
- Query parameters in URL: None
# Response
Success
Code: 200
Return value:
{ "value": { "id": "Block id", "events": [ { "txIndex": "Index used for managing transaction for events", "txId": "Transaction id", "triggeredEvent": "List of triggered events including data", "filterData": "Bloom filter of events for quick search" } ] }, "atHeight": "Current block height at the time of response" }
Validation Error
- Code: 400
- Reason:
- Id is not a valid ByteString
Object Not Found
- Code: 404
- Reason:
- Block does not exist
# Get Block Events by Height
Returns the events for the block at given height.
# Request
- Method: GET
- URL: /blockevents/height/{height}
- Query parameters in URL: None
# Response
Success
Code: 200
Return value:
{ "value": { "id": "Block id", "events": [ { "txIndex": "Index used for managing transaction for events", "txId": "Transaction id", "triggeredEvent": "List of triggered events including data", "filterData": "Bloom filter of events for quick search" } ] }, "atHeight": "Current block height at the time of response" }
Validation Error
- Code: 400
- Reason:
- Height is not an integer
Object Not Found
- Code: 404
- Reason:
- Block does not exist
# Get Peers count
Returns the number of peers the node is currently connected to.
# Request
- Method: GET
- URL: /peercount
- Query Parameters in URL: None
# Response
- Success
Code: 200
Return value:
{ "value": "The number of peers the node is currently connected to", "atHeight": "Current block height at the time of response" }
# Get Peers
Returns the list of public keys of the peers the node is currently connected to.
# Request
- Method: GET
- URL: /peers
- Query Parameters in URL: None
# Response
- Success
Code: 200
Return value:
{ "value": [ "The pubic keys of peers the node is currently connected to" ], "atHeight": "Current block height at the time of response" }
# Get Node Type
Returns true or false depending on whether the node is a core one.
# Request
- Method: GET
- URL: /iscore
- Query Parameters in URL: None
# Response
- Success
Code: 200
Return value:
{ "value": "True/False represents if the connected node is a consensus node", "atHeight": "Current block height at the time of response" }
# Send Transaction
Submit a transaction to Miyabi. It must contain the transaction information on the request body. The value returned is the integral validation check of the transaction, not the actual result of it.
# Request
Method: POST
URL: /sendtx
Query Parameters in URL: None
Body:
{ { "entryDetails": [ { "typeName": "Name of the table type", "entryDetails": { "name": "Name of the table", "tracked": "Flag to indicate if the transaction's history is recorded", "supportProofs": "Flag to indicate if the transaction's table supports `proofs` or not", "tableAcl": { "tableOwners": [ <List of table owners> ], "permissions": [], "multiKeyPermissions": [] }, "isReadRestricted": "Flag to indicate if the transaction's table is `ReadRestricted` or not", "permissionModel": "Permission model number" } } ], "timestamp": "Tx execution DateTime", "validFrom": "Tx validity start DateTime", "validTo": "Tx validity end DateTime", "entries": [ <List of transaction entries> ], "requiredCredentials": [ <List of required credentials> ], "evidence": [ <List of transaction evidence> ], "id": "Transaction id", "witId": "Transaction witId" } }
# Response
Success
Code: 200
Return value:
{ "value": "Transaction Result Code(Duplicated, pending...)", "atHeight": "Current block height at the time of response" }
Validation Error
- Code: 400
- Reason:
- Transaction Request is not complete or illegal.
# Send Transactions
Submit transactions to Miyabi. The value returned is the integral validation check of the transactions, not the actual result of them.
# Request
Method: POST
URL: /sendtxs
Query Parameters in URL: None
Body:
{ [ { "entryDetails": [ { "typeName": "Name of the table type", "entryDetails": { "name": "Name of the table", "tracked": "Flag to indicate if the transaction's history is recorded", "supportProofs": "Flag to indicate if the transaction's table supports `proofs` or not", "tableAcl": { "tableOwners": [ <List of table owners> ], "permissions": [], "multiKeyPermissions": [] }, "isReadRestricted": "Flag to indicate if the transaction's table is `ReadRestricted` or not", "permissionModel": "Permission model number" } } ], "timestamp": "Tx execution DateTime", "validFrom": "Tx validity start DateTime", "validTo": "Tx validity end DateTime", "entries": [ <List of transaction entries> ], "requiredCredentials": [ <List of required credentials> ], "evidence": [ <List of transaction evidence> ], "id": "Transaction id", "witId": "Transaction witId" } ] }
# Response
Success
Code: 200
Return value:
{ "value": [ "<List of TransactionResultCodes>" // Transaction Result Code of the sent transactions, ], "atHeight": "Current block height at the time of response" }
Validation Error
- Code: 400
- Reason:
- Transaction Requests are not complete or illegal.
# Get Transaction Info by Id
Returns the transaction information for a given transaction Id.
# Request
- Method: GET
- URL: /tx/{id}
- Query Parameters in URL: None
# Response
Success
Code: 200
Return value:
{ "value": [ { "tx": { "entryDetails": [ { "typeName": "Name of the table type", "entryDetails": { "name": "Name of the table", "tracked": "Flag to indicate if the transaction's history is recorded", "supportProofs": "Flag to indicate if the transaction's table supports `proofs` or not", "tableAcl": { "tableOwners": [ <List of table owners> ], "permissions": [], "multiKeyPermissions": [] }, "isReadRestricted": "Flag to indicate if the transaction's table is `ReadRestricted` or not", "permissionModel": "Permission model number" } } ], "timestamp": "Tx execution DateTime", "validFrom": "Tx validity start DateTime", "validTo": "Tx validity end DateTime", "entries": [ <List of transaction entries> ], "requiredCredentials": [ <List of required credentials> ], "evidence": [ <List of transaction evidence> ], "id": "Transaction id", "witId": "Transaction witId" }, "txPtr": { "height": "Transaction pointer height", "idx": "Transaction index" }, "result": "Success or failure" } ], "atHeight": "Current block height at the time of response" }
Validation Error
- Code: 400
- Reason:
- Id is not a valid ByteString
Object Not Found
- Code: 404
- Reason:
- Transaction does not exist in the memory pool or any block
# Get Transactions Info by Ids
Returns the transaction information from a given list of transaction ids.
# Request
- Method: POST
- URL: /txs
- Query Parameters in URL: None
- Body:
[ "transactionId1", "transactionId2" ]
# Response
Success
Code: 200
Return value:
{ "value": [ { "tx": { "entryDetails": [ { "typeName": "CreateEntityTable", "entryDetails": { "name": "Table name", "tracked": "Flag to indicate if the transaction's history is recorded", "supportProofs": "Flag to indicate if the transaction's table supports `proofs` or not", "tableAcl": { "tableOwners": [ <List of table owners> ], "permissions": [], "multiKeyPermissions": [] }, "isReadRestricted": "Flag to indicate if the transaction's table is `ReadRestricted` or not", "permissionModel": "Permission model number" } } ], "timestamp": "Tx execution DateTime", "validFrom": "Tx validity start DateTime", "validTo": "Tx validity end DateTime", "entries": [ <List of transaction entries> ], "requiredCredentials": [ <List of required credentials> ], "evidence": [ <List of transaction evidence> ], "id": "Transaction id", "witId": "Transaction witId" }, "txPtr": { "height": "Transaction pointer height", "idx": "Transaction index" }, "result": "Success or failure" } ], "atHeight": "Current block height at the time of response" }
Validation Error
- Code: 400
- Reason:
- Id is not a valid ByteString
Object Not Found
- Code: 404
- Reason:
- Transaction does not exist in any block (Note: For multiple transactions, the transaction id is not looked up in the mempool to avoid performance issues)
# Get Transaction Result by Id
Returns the result of a previously submitted transaction from a given transaction id.
# Request
- Method: GET
- URL: /tx/result/{id}
- Query Parameters in URL: None
# Response
Success
Code: 200
Return value:
{ "value": { "resultCode": "The transaction result code of the transaction id", "errorMessage": "Exception information if the transaction failed." }, "atHeight": "Current block height at the time of response" }
Validation Error
- Code: 400
- Reason:
- Id is not a valid ByteString
Object Not Found
- Code: 404
- Reason:
- Transaction does not exist in memory pool and blocks
# Get Transaction Results by Id's
Returns the result of previously submitted transactions from a given transaction id list.
# Request
Method: POST
URL: /txresults
Query Parameters in URL: None
Body:
{ "transactionResultsRequest": [<List of TransactionResultCode>] }
# Response
Success
Code: 200
Return value:
{ "value": [<List of TransactiionResultCode>] ,// the result code of each specified transactions, "atHeight": "Current block height at the time of response" }
Validation Error
- Code: 400
- Reason:
- Id is not a valid ByteString
# Get Transaction List by Height
Returns a set of transactions contained in the block of the specific height.
# Request
- Method: GET
- URL: /txlist/{height}
- Query Parameters in URL: None
# Response
Success
Code: 200
Return value:
{ "value": [ { "tx": { "timestamp": "Tx execution DateTime", "validFrom": "Tx validity start DateTime", "validTo": "Tx validity end DateTime", "entries": [ <List of transaction entries> ], "requiredCredentials": [ <List of required credentials> ], "evidence": [ <List of transaction evidence> ], "id": "Transaction id", "witId": "Transaction witId" }, "txPtr": { "height": "Transaction pointer height", "idx": "Transaction index" }, "result": "Success or failure" } ], "atHeight": "Current block height at the time of response" }
Validation Error
- Code: 400
- Reason:
- Height is not an integer
Object Not Found
- Code: 404
- Reason:
- Block does not exist
# Get Performance of Node
Returns the performance information on the node.
# Request
- Method: GET
- URL: /performance
- Query Parameters in URL: None
# Response
- Success
Code: 200
Return value:
{ "value": { "StatsStartHeight": "The height at which the statistics computation has started", "TxPerBlock": "Transactions per block statistics", "TransactionsPerSecond": "Transactions per second statistics", "BlockConfirmationTime": "Block confirmation time statistics" }, "atHeight": "Current block's height when requested" }
# Get Key History
Returns a list containing the transaction ids that have modified a given key in a table. The table should have 'Tracked' enabled.
# Request
- Method: GET
- URL: /history/{tableName}/{key}
- Query Parameters in URL: None
# Response
Success
Code: 200
Return value:
{ "value": [ <List of transaction Id> // Id of transactions that modified this entry ], "atHeight": "Current block height at the time of response" }
Validation Error
- Code: 400
- Reason:
- Key is not a valid ByteString
Object Not Found
- Code: 404
- Reason:
- Transaction history does not exist.
# Get Detailed Key History
Returns a list containing the transaction details of the transactions that have modified a given key in a table. The table should have 'Tracked' enabled
# Request
- Method: GET
- URL: /history/{tableName}/{key}/detail
- Query Parameters in URL: None
# Response
Success
Code: 200
Return value:
{ "value": [ { "tx": { "timestamp": "Tx execution DateTime", "validFrom": "Tx validity start DateTime", "validTo": "Tx validity end DateTime", "entries": [ <List of transaction entries> ], "requiredCredentials": [ <List of required credentials> ], "evidence": [ <List of transaction evidence> ], "id": "Transaction id", "witId": "Transaction witId" }, "txPtr": { "height": "Transaction pointer height", "idx": "Transaction index" }, "result": "Success or failure" } ], "atHeight": "Current block height at the time of response" }
Validation Error
- Code: 400
- Reason:
- Key is not a valid ByteString
Object Not Found
- Code: 404
- Reason:
- Transaction history does not exist.
# Get Memory Pool Count
Returns the number of transactions currently stored in the memory pool of the node.
# Request
- Method: GET
- URL: /mempool/count
- Query Parameters in URL: None
# Response
- Success
Code: 200
Return value:
{ "value": "The number of transactions in the node's memory pool", "atHeight": "Current block height at the time of response" }
# Get Consensus Credentials of Height
Returns a list of the consensus members credentials at the current height (default) or given height. The atHeight field of the response is always the current height of the node while the value field contains the list of credentials of the consensus nodes at the height that was requested.
# Request
- Method: GET
- URL: /consensus/credentials
- Query parameters in URL: Height
# Response
- Success
Code: 200
Return value:
{ "value": { "members": [ "The credentials for individual participants in consensus" ], "quorumCredentials": [ "Credentials for the quorum itself, in the case of multisig" ] }, "atHeight": "Current block height at the time of response" }
# Get Consensus Peers
Returns a list of the consensus peers that are connected to this node. The credentials of the current node will not be included in the list.
# Request
- Method: GET
- URL: /consensus/peers
- Query parameters in URL:
# Response
- Success
Code: 200
Return value:
{ "value": [ "<List of credentials>" // "Credentials of consensus peers" ], "atHeight": "Current block height at the time of response" }
# Get State Proof
Returns a proof for the given entry key and table. The proof of existence is a bundle of hashes to prove the value hash of the specified item belongs to the Merkle tree of the root hash.
# Request
- Method: GET
- URL: /stateproof/{tableName}/{entryKey}
- Query parameters in URL: None
# Response
Success
Code: 200
Return value:
{ "value": { "TableProof": "Proof of existence for table", "TableEntryProof": "Proof of existence for entry" }, "atHeight": "Current block height at the time of response" }
Validation Error
- Code: 400
- Reason:
- entryKey is not a valid ByteString
Object Not Found
- Code: 404
- Reason:
- Table or entry does not exist
# Get Blockchain Parameters
Returns the information of the blockchain related parameters
# Request
- Method: GET
- URL: /blockchainparameters
- Query parameters in URL:
# Response
Success
Code: 200
Return value:
{ "value": { "maxtpb":"The maximum number of transactions allowed per block", "emptyBlocks":"Is empty block generation allowed", "transactionLifetime":"Maximum allowed transaction lifetime", "byzantineAssumption":"Is byzantine assumption set to true or false", "evidenceValidatorType":"Type of validator used to validate the evidence", "maxClockDrift":"Max clock drift. (Used to adjust time-related calculations in block execution for potential timer difference)", "networkName":"Name of the network. (designed for sharding, not use for now)", "initScript":" Initialization script. (entries for initializing the tables/state with root permission)", "extensions": [ { "name": "Module name", "publicKey": "Public key if any" } ], "blockLimit":{ "MaxEntriesPerTransaction":"Maximum entries per transaction", "MaxTransactionByteSize":"Maximum size of a transaction" } }, "atHeight": "Current block height at the time of response" }
Validation Error
- Code: 400
- Reason:
- Validation error or invalid Height