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

OK
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.

Tx

  • 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

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

Subscribe Endpoint

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

OK
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

Subscribe 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 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.