# General Web 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 about the node

# Request

Method: GET
URL: /getinfo
Query parameters in URL: None

# Response

Success:

Code: 200

Return value:

{
  "value": {
    "version": "Provides version information about the Miyabi library",
    "status": "Current status reported by the node",
    "starttime": "Time at whih node was started",
    "height": "Current block height of the node",
    "mempoolSize": "Number of entries in the memory pool",
    "identity": "The node's consensus address",
    "role": "Type of node 'Consensus/Application' node",
    "connections": [{
      "identity":"Network identity/credential of the node",
      "endpoint":"Endpoint for the network layer for the node",
      "configured":"'true' if the node is configured on the 'nodeconfig'",
      "status":"'Connected' if the calling node has any connection to the node else 'Disconnected' ",
    }],
    "extensions":[<List of Loaded Modules>]
  },
  "atHeight": "Current block's height when requested"
}

# 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 table",
      "tracked": "Option for tracking the history of the table",
      "supportProofs": "Option to determine if the table allows to check for 'Proofs' or not"
    }
  ],
  "atHeight": "Current block's height when requested"
}

# Get Current Height

Returns the height of the blockchain 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's height when requested"
}

# Get Blocks with 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": [
    {
      "height": "Block height",
      "id": "Block ID",
      "txCount": "The number of transactions in the block",
      "sizeBytes": "The size of this block",
      "body": "The block body of this block",
      "header": "The header of this block",
      "evidence": "The signatures of this block from consensus nodes"
    }
  ],
  "atHeight": "Current block's height when requested"
}

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

# Get Block with 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": {
    "height": "Block height",
    "id": "Block ID",
    "txCount": "The number of transactions in the block",
    "sizeBytes": "The size of this block",
    "body": "The block body of this block",
    "header": "The header of this block",
    "evidence": "The signatures of this block from consensus nodes"
  },
  "atHeight": "Current block's height of the request"
}

Object Not Found
- Code: 404
- Reason:
  - Block does not exist
Validation Error
- Code: 400
- Reason:
  - ID is not a Byte string

# Get Block with 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": {
    "height": "Block height",
    "id": "Block ID",
    "txCount": "The number of transactions in the block",
    "sizeBytes": "The size of this block",
    "body": "The block body of this block",
    "header": "The header of this block",
    "evidence": "The signatures of this block from consensus nodes"
  },
  "atHeight": "Current block's height when requested"
}

Object Not Found
- Code: 404
- Reason:
  - Block does not exist
Validation Error
- Code: 400
- Reason:
  - Height is not an integer

# Get Block Headers with 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",
      "evidence": "The signatures of this block from consensus nodes"
    }
  ],
  "atHeight": "Current block's height when requested"
}

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

# Get Header with 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",
    "evidence": "The signatures of this block from consensus nodes"
  },
  "atHeight": "Current block's height when requested"
}

Object Not Found
- Code: 404
- Reason:
  - Block does not exist
Validation Error
- Code: 400
- Reason:
  - ID is not a Byte string

# Get Header with 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",
    "evidence": "The signatures of this block from consensus nodes"
  },
  "atHeight": "Current block's height when requested"
}

Object Not Found
- Code: 404
- Reason:
  - Block does not exist
Validation Error
- Code: 400
- Reason:
  - Height is not an integer

# Get Block Events with Block ID

Returns the block events from 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",
    "TransactionEventsInfo": [
      {
        "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's height when requested"
}

Object Not Found
- Code: 404
- Reason:
  - Block or events does not exist
Validation Error
- Code: 400
- Reason:
  - ID is not a Byte string

# Get Block Events with 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",
    "TransactionEventsInfo": [
      {
        "TxIndex": "Index used for managing transactions for events",
        "TxId": "Transaction ID",
        "TriggeredEvent": "List of triggered events including data",
        "FilterData": "Bloom filter of events for quick search"
      }
    ]
  },
  "atHeight": "Current block's height when requested"
}

Object Not Found
- Code: 404
- Reason:
  - Block or events does not exist
Validation Error
- Code: 400
- Reason:
  - Height is not an integer

# 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's height when requested"
}

# Get Peers

Returns the list of public keys of the peers the node is currently connected to. This list does not include the one from the queried node.

# 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's height when requested"
}

# Get Transaction Info By Id

Returns the transaction information from a given transaction Id.

# Request

Method: GET
URL: /tx/{id}
Query Parameters in URL: None

# Response

Success

Code: 200

Return value:

{
  "value": {
    "Transaction": "The original transaction",
    "TransactionPointer": {
      "height": "The block height of the transaction if committed",
      "txIndex": "The transaction index within the block"
    },
    "Result": "Transaction Result Code"
  },
  "atHeight": "Current block's height when requested"
}

Object Not Found
- Code: 404
- Reason:
  - Transaction does not exist in the memory pool or any block
Validation Error
- Code: 400
- Reason:
  - ID is not a valid byte string

# Get Transaction Infos 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": [
    {
      "Transaction": "The original transaction",
      "TransactionPointer": {
        "height": "The block height of the transaction if committed",
        "txIndex": "The transaction index within the block"
      },
      "Result": "Transaction Result Code"
    }
  ],
  "atHeight": "Current block's height when requested"
}

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)
Validation Error
- Code: 400
- Reason:
  - ID is not a valid byte string

# 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 result code of the transaction",
    "ErrorMessage": "Exception information if the transaction failed."
  },
  "atHeight": "Current block's height when requested"
}

Object Not Found
- Code: 404
- Reason:
  - Transaction does not exist in memory pool and blocks
Validation Error
- Code: 400
- Reason:
  - ID is not a valid byte string

# Get Transaction Results By IDs

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 Result Code>] ,// the result code of each specified transactions,
  "atHeight": "Current block's height when requested"
}

Validation Error
- Code: 400
- Reason:
  - ID is not a valid byte string

# 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": [
    {
      "Transaction": "The original transaction",
      "TransactionPointer": {
        "height": "The block height of the transaction if committed",
        "txIndex": "The transaction index within the block"
      },
      "Result": "Transaction Result Code"
    }
  ],
  "atHeight": "Current block's height when requested"
}

Object Not Found
- Code: 404
- Reason:
  - Block does not exist
Validation Error
- Code: 400
- Reason:
  - Height is not a valid byte string

# Get Performance of Node

Returns the performance information of the node.

# Request

Method: GET
URL: /performace
Query Parameters in URL: None

# Response

Success

Code: 200

Return value:

{
  "value": {
    "StatsStartHeight": "The height at which the statistics computation has started.",
    "TxPerBlock": "A value set for transactions",
    "TransactionsPerSecond": "A value set for transactions per second.",
    "BlockConfirmationTime": "A value set for block confirmation time."
  },
  "atHeight": "Current block's height when requested"
}

# Get History of Row

Returns a list containing the transaction history from a given key and table.

# Request

Method: GET
URL: /history/{tableName}/{key}
Query Parameters in URL: None

# Response

Success

Code: 200

Return value:

{
  "value": [
    "<List of txId>" // ID of transactions that modified this entry
  ],
  "atHeight": "Current block's height when requested"
}

Object Not Found
- Code: 404
- Reason:
  - Transaction history does not exist.
Validation Error
- Code: 400
- Reason:
  - Key is not a valid byte string

# Get History detail of Row

Returns a list containing a detailed history from a given key and table.

# Request

Method: GET
URL: /history/{tableName}/{key}/detail
Query Parameters in URL: None

# Response

Success

Code: 200

Return value:

{
  "value": [
    {
      "Transaction": "The original transaction",
      "TransactionPointer": {
        "height": "The block height of the transaction if committed",
        "txIndex": "The transaction index within the block"
      },
      "Result": "Transaction Result Code"
    }
  ],
  "atHeight": "Current block's height when requested"
}

Object Not Found
- Code: 404
- Reason:
  - Transaction history does not exist.
Validation Error
- Code: 400
- Reason:
  - Key is not a valid byte string

# 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 amount of transactions in memory pool",
  "atHeight": "Current block's height when requested"
}

# Get Node Type

Returns true or false depending if the node is a core one or not.

# 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's height when requested"
}

# Get Consensus Credentials of Height

Returns a list of the consensus members credentials at the current height or from a 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": {
    "ConsensusCredentials": {
      "Members": "The credentials for individual participants in consensus.",
      "QuorumCredentials": "Credentials for the quorum itself, in the case of multisig."
    }
  },
  "atHeight": "Current block's height when requested"
}

# 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's height when requested"
}

# 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":"<List of extensions>",
    "BlockLimit":{
      "MaxEntriesPerTransaction":"Maximum entries per transaction",
      "MaxTransactionByteSize":"Maximum size of a transaction"
    }
  },
  "atHeight": "Current block's height when requested"
}

# Get Block Limit

Returns the information of the transactions size and 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's height when requested"
}

# 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's height when requested"
}

Object Not Found
- Code: 404
- Reason:
  - Table or entry does not exist
Validation Error
- Code: 400
- Reason:
  - entryKey is not a Byte string .

# Send Transaction

Submit a transaction to be added to the memory pool of a node if valid. It has to 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:

  {
    "transactionRequest": {
      "Timestamp": "Time of the transaction generation",
      "ValidFrom": "Start time of the transaction’s validity",
      "ValidTo": "End time of the transaction’s validity",
      "Entries": "Transaction entries, can be created from client sdk",
      "RequiredCredentials": "The public keys of signers",
      "Evidence": "Signature of the transaction from signers"
    }
  }

# Response

Success

Code: 200

Return value:

{
  "value": "Transaction Result Code(Duplicated, pending...)",
  "atHeight": "Current block's height when requested"
}

Validation Error
- Code: 400
- Reason:
  - Transaction Request is not complete or illegal.

# Send Transactions

Submit a set of transactions to be added to the memory pool of the node if all of them are valid. 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:

  {
    "transactionRequests": [
      {
        "Timestamp": "Time of the transaction generation",
        "ValidFrom": "Start time of the transaction’s validity",
        "ValidTo": "End time of the transaction’s validity",
        "Entries": "Transaction entries, can be created from clientsdk",
        "RequiredCredentials": "The public keys of signers",
        "Evidence": "Signature of the transaction from signers"
      }
    ]
  }

# Response

Success

Code: 200

Return value:

{
  "value": [
    "<List of TransactionResultCodes>" // Transaction Result Code of the sent transactions,
  ],
  "atHeight": "Current block's height when requested"
}

Validation Error
- Code: 400
- Reason:
  - Transaction Requests are not complete or illegal.

← Introduction Admin API →