Catalyst Blockchain Manager API

For communication between your business application and a chaincode, Catalyst Blockchain Manager provides you with an API to invoke/query deployed chaincodes and subscribe for chaincode events.

Catalyst Blockchain Manager API can be used by the users who have an on-premise installation of Catalyst Blockchain Manager. The users who use Catalyst Blockchain Manager as a BaaS will be able to use the API in future releases.

Invoke Endpoint

POST {domain}/api/v1/channels/{channelID}+eventfiltervalue/cc/{chaincodeID/}+invoke

Content-type - application/json

Parameters

Path

Domain*

String

The name of the domain, where the catalyst Blockchain Platform Fabric service is deployed

ChannelID*

String

The name of the channel, where the chaincode is committed

ChaincodeID*

String

The Chaincode name

Body

function*

String

The name of a chaincode function

args*

Array

An array of function arguments

transient_args

Object

Transient args will reach the chaincode but will not stay in the transaction records

is_init

Boolean

Indicates whether the init function call is required. It can only be set to true during the first operation with chaincode.

Responses

200

Response:

{
  "proposal_response": {
		"chaincode_status": 0, //200 or 500
		"payload": "", //base64
    "errors": [
      {
        "code": 0,
        "message": "string"
      }
    ]
  },
  "tx": {
    "id": "string",
    "validation_code": 0
  }
}

400	Bad Request

500	Internal Server Error

Request

Example of the request body for invocation of a chaincode:

 {
    "args": ["data"],
    "transient_args": {
        "asset_properties": {
            "assetID": "99",
            "objectType": "art",
            "color": "black",
            "size": 500,
            "appraisedValue": 999
        }
    },
    "function": "CreateAsset",
    "is_init": false,
 }

Response

 {
  "proposal_response": {
		"chaincode_status": 0, //200 or 500
		"payload": "", //base64
    "errors": [
      {
        "code": 0,
        "message": "string"
      }
    ]
  },
  "tx": {
    "id": "string",
    "validation_code": 0
  }
}

Proposal Response

chaincode_status - shows the response from a chaincode. Possible values in the current version: 200 and 500.
- The 500 status means that execution failed for some reason. Note that it might be a business error like thrown exception “entity not found”. There can be multiple reasons of failure due to proposals being sent to multiple peers. The reasons can be found in errors.
errors - tatus error returned from a peer.
- The message is equal to the text in exception chaincode throws. It is suggested that instead of plain string in the message you should use a data structure with all the info about what happened and some custom codes.
payload - data returned on successful invocation/query from a chaincode in base64.

id - transaction id that is generated for each request, must be unique.
tv_validation_code - validation code of a transaction set by ordering service. It makes sense to check this code only if chaincode_status is 200. Even if chaincode_status is 200, it does not mean that the transaction was approved and valid. It’s important that the validation code must be 0 for any valid transaction.

All possible codes are listed below.

TxValidationCode_VALID 			      TxValidationCode = 0
TxValidationCode_NIL_ENVELOPE                 TxValidationCode = 1
TxValidationCode_BAD_PAYLOAD                  TxValidationCode = 2
TxValidationCode_BAD_COMMON_HEADER            TxValidationCode = 3
TxValidationCode_BAD_CREATOR_SIGNATURE        TxValidationCode = 4
TxValidationCode_INVALID_ENDORSER_TRANSACTION TxValidationCode = 5
TxValidationCode_INVALID_CONFIG_TRANSACTION   TxValidationCode = 6
TxValidationCode_UNSUPPORTED_TX_PAYLOAD       TxValidationCode = 7
TxValidationCode_BAD_PROPOSAL_TXID            TxValidationCode = 8
TxValidationCode_DUPLICATE_TXID               TxValidationCode = 9
TxValidationCode_ENDORSEMENT_POLICY_FAILURE   TxValidationCode = 10
TxValidationCode_MVCC_READ_CONFLICT           TxValidationCode = 11
TxValidationCode_PHANTOM_READ_CONFLICT        TxValidationCode = 12
TxValidationCode_UNKNOWN_TX_TYPE              TxValidationCode = 13
TxValidationCode_TARGET_CHAIN_NOT_FOUND       TxValidationCode = 14
TxValidationCode_MARSHAL_TX_ERROR             TxValidationCode = 15
TxValidationCode_NIL_TXACTION                 TxValidationCode = 16
TxValidationCode_EXPIRED_CHAINCODE            TxValidationCode = 17
TxValidationCode_CHAINCODE_VERSION_CONFLICT   TxValidationCode = 18
TxValidationCode_BAD_HEADER_EXTENSION         TxValidationCode = 19
TxValidationCode_BAD_CHANNEL_HEADER           TxValidationCode = 20
TxValidationCode_BAD_RESPONSE_PAYLOAD         TxValidationCode = 21
TxValidationCode_BAD_RWSET                    TxValidationCode = 22
TxValidationCode_ILLEGAL_WRITESET             TxValidationCode = 23
TxValidationCode_INVALID_WRITESET             TxValidationCode = 24
TxValidationCode_INVALID_CHAINCODE            TxValidationCode = 25
TxValidationCode_NOT_VALIDATED                TxValidationCode = 254
TxValidationCode_INVALID_OTHER_REASON         TxValidationCode = 255

Query Endpoint

Request

POST {domain}/api/v1/channels/{channelID}/cc/{chaincodeID/}query

Content-type - application/json

Parameters

Path

Domain*

String

The name of the domain, where the catalyst Blockchain Platform Fabric service is deployed

ChannelID*

String

The name of the channel, where the chaincode is committed

ChaincodeID*

String

The Chaincode name

Body

function*

String

The name of a chaincode function

args*

Array

An array of function arguments

transient_args

Object

Transient args will reach the chaincode but will not stay in the transaction records

is_init

Boolean

Indicates whether the init function call is required. It can only be set to true during the first operation with chaincode.

use_local_peers

Boolean

Set to true if you want to use only the peers that belong to your organization

Responses

200

Response:

  {
  "proposal_response": {
		"chaincode_status": 0, //200 or 500
		"payload": "", //base64
    "errors": [
      {
        "code": 0,
        "message": "string"
      }
    ]
  },
  "tx": {
    "id": "string",
    "validation_code": 0
  }
}

400	Bad Request

500	Internal Server Error

Example of the request body for the query of a chaincode:

{
    "args": ["data"],
    "transient_args": {
        "asset_properties": {
            "assetID": "99",
            "objectType": "art",
            "color": "black",
            "size": 500,
            "appraisedValue": 999
        }
    },
    "function": "CreateAsset",
    "is_init": false,
    "use_local_peers": false
}

Response

 {
  "proposal_response": {
		"chaincode_status": 0, //200 or 500
		"payload": "", //base64
    "errors": [
      {
        "code": 0,
        "message": "string"
      }
    ]
  },
  "tx": {
    "id": "string",
    "validation_code": 0
  }
}

Server-Sent Events (SSE) is a server push technology enabling a client to receive automatic updates from a server via an HTTP connection. This specific endpoint allows you to subscribe to an event stream for a specific chaincode.

Request

GET {domain}/api/v1/channels/{channelID}/cc/{chaincodeID}/subscibe??startFrom={startFromValue}&eventFilter={eventFilterValue}

Content-type - application/json

Parameters

Path

Domain*

String

The name of the domain, where the catalyst Blockchain Platform Fabric service is deployed

ChannelID*

String

The name of the channel, where the chaincode is committed

ChaincodeID*

String

The Chaincode name

Query

{startFromValue}

Integer

Block number (last block set by default)

{eventFilterValue}

String

Regexp to filter out only the needed events

Responses

200

Response:

 "tx_id": "string",
"chaincode_id": "string",
"event_name": "string",
"payload": "", //base64
"block_number": 0

Response

"tx_id": "string",
"chaincode_id": "string",
"event_name": "string",
"payload": "", //base64
"block_number": 0

tx_id - the id of the transaction in which the event was set.
chaincode_id - the id of the chaincode that set the event.
event_name - the name of the chaincode event.
payload - contains the payload of the chaincode event is base64.
true - contains the block number in which the chaincode event was committed.

Examples

Catalyst Blockchain Manager supports two authorization types: Basic and OpenID.

The user chooses the authorization type during the Catalyst Blockchain Manager Hyperledger Fabric service installation.

Invoke example

The name of the domain, where Catalyst Blockchain Manager service is deployed: chaincodeinvokeexample.com
The channel name: catbp
The chaincode name: helloworld
Auth type: basic auth (login: login, password: password)

curl -X POST https://chaincodeinvokeexample.com/api/v1/channels/catbp/cc/helloworld/invoke
 -H 'Content-Type: application/json'
 -H 'Authorization: Basic bG9naW46cGFzc3dvcmQK'
 -d '{"function":"save","args":["John"],"is_init":false}'

where bG9naW46cGFzc3dvcmQK — base64 authorization token

You can generate the token using the following command echo {your_login}:{your_password} | base64

Query example

The name of the domain, where Catalyst Blockchain Manager service is deployed: chaincodeinvokeexample.com
The channel name: catbp
The chaincode name: helloworld
Auth type: OpenID

curl -X POST https://chaincodequeryexample.com/api/v1/channels/catbp/cc/helloworld/query
 -H 'Content-Type: application/json'
 -H 'Authorization: Bearer b3BlbmlkOm9wZW5pZAo='
 -d '{"function":"get","args":["John"],"is_init":false}'

where b3BlbmlkOm9wZW5pZAo — base64 authorization token

The name of the domain, where Catalyst Blockchain Manager service is deployed: chaincodeinvokeexample.com
The channel name: catbp
The chaincode name: helloworld
Auth type: OpenID

curl -X GET https://chaincodesubscriptionexample.com/api/v1/channels/catbp/cc/helloworld/subscribe
 -H 'Content-Type: text/event-stream'
 -H 'Authorization: Bearer b3BlbmlkOm9wZW5pZAo='

Where b3BlbmlkOm9wZW5pZAo= is your OpenID token.

Catalyst Blockchain Manager API

Invoke Endpoint

Request

Response

Query Endpoint

Request

Response

Subscribe Endpoint

Request

Response

Examples

Invoke example

Query example

Subscribe example