Jump to

• Request
• Response
• Examples

Subscribe to an Event

post

/restproxy/api/v2/channels/{channelId}/event-subscriptions

Subscribe to an event

Request

Supported Media Types

• application/json

Path Parameters

• channelId: string
  ID of the channel

Body ()

Request to subscribe to an event

Root Schema : eventSubscription

Type: object

Show Source

• block(optional): integer(int64)
  Number of the block
• callbackTLSCerts: object callbackTLSCerts
• callbackURL: string
  Callback URL
• chaincode(optional): string
  Name of the chaincode
• event(optional): string
  Name of the event
• expires(optional): string
  Expiration of the subscription
• role(optional): string
  Name of Fabric enrollment to be used
• seek(optional): string
  Allowed Values: [ "oldest", "newest", "from" ]

  Start position of the event. Only used for type "block" and "filteredblock"
• txid(optional): string
  ID of the transaction
• type: string
  Allowed Values: [ "block", "filteredblock", "transaction", "chaincode" ]

  event type to subscribe to

{
    "type":"object",
    "required":[
        "type",
        "callbackURL",
        "callbackTLSCerts"
    ],
    "properties":{
        "role":{
            "description":"Name of Fabric enrollment to be used",
            "type":"string"
        },
        "type":{
            "description":"event type to subscribe to",
            "type":"string",
            "enum":[
                "block",
                "filteredblock",
                "transaction",
                "chaincode"
            ]
        },
        "callbackURL":{
            "description":"Callback URL",
            "type":"string"
        },
        "callbackTLSCerts":{
            "type":"object",
            "properties":{
                "caCert":{
                    "type":"string"
                },
                "clientCert":{
                    "type":"string"
                },
                "keyPassword":{
                    "type":"string"
                }
            }
        },
        "expires":{
            "description":"Expiration of the subscription",
            "type":"string"
        },
        "txid":{
            "description":"ID of the transaction",
            "type":"string"
        },
        "chaincode":{
            "description":"Name of the chaincode",
            "type":"string"
        },
        "event":{
            "description":"Name of the event",
            "type":"string"
        },
        "seek":{
            "description":"Start position of the event. Only used for type \"block\" and \"filteredblock\"",
            "type":"string",
            "enum":[
                "oldest",
                "newest",
                "from"
            ]
        },
        "block":{
            "description":"Number of the block",
            "type":"integer",
            "format":"int64"
        }
    }
}

Nested Schema : callbackTLSCerts

Type: object

Show Source

• caCert(optional): string
• clientCert(optional): string
• keyPassword(optional): string

{
    "type":"object",
    "properties":{
        "caCert":{
            "type":"string"
        },
        "clientCert":{
            "type":"string"
        },
        "keyPassword":{
            "type":"string"
        }
    }
}

Back to Top

Response

Supported Media Types

• application/json

200 Response

Operation successful

Body ()

Root Schema : schema

Type: object

Show Source

• error(optional): string
  Default Value:

  Error message when operation fails
• result(optional): object result
• returnCode: string
  Allowed Values: [ "Success", "Failure" ]

{
    "type":"object",
    "required":[
        "returnCode"
    ],
    "properties":{
        "returnCode":{
            "$ref":"#/definitions/returnCode"
        },
        "error":{
            "type":"string",
            "description":"Error message when operation fails",
            "default":""
        },
        "result":{
            "type":"object",
            "required":[
                "subid"
            ],
            "properties":{
                "subid":{
                    "description":"ID of the subscription when operation succeeds",
                    "type":"string"
                }
            }
        }
    }
}

Nested Schema : result

Type: object

Show Source

• subid: string
  ID of the subscription when operation succeeds

{
    "type":"object",
    "required":[
        "subid"
    ],
    "properties":{
        "subid":{
            "description":"ID of the subscription when operation succeeds",
            "type":"string"
        }
    }
}

400 Response

Bad Request

401 Response

Not authorized

403 Response

Forbidden

404 Response

Invalid parameters

500 Response

Service unavailable

Back to Top

Examples

This endpoint is used to request an event subscription.

The following example shows how to request an event subscription by submitting a POST request on the REST resource using cURL.

curl -v -u <username>:<password> -X POST \
  "https://<restproxy of your Blockchain instance>/api/v2/channels/default/event-subscriptions" \
  -H "accept: application/json" \
  -H "Content-Type: application/json" \
  --data @<JSON file with the request parameters>

For example,

curl -v -u obpuser:<password> -X POST \
  "https://myvm.oracle.com:10000/restproxy/api/v2/channels/default/event-subscriptions" \
  -H "accept: application/json" \
  -H "Content-Type: application/json" \
  --data @file.json

The contents of file.json are:

{
 "role": "myinstance_defaultuser",
 "type": "chaincode",
 "callbackURL": "http://10.168.108.17:9000",
 "expires": "1m", 
 "callbackTLSCerts": { 
   "caCert": "",
   "clientCert": "",
   "keyPassword": "" },
 "txid": "b1c11242383212cfdcca97d68efc0b3641436b1845a9b4c6e822cf6099ca49ee",
 "chaincode": "obcs-example02",
 "seek": "oldest", 
 "block": 0,
 "event": ".*"
}

Where each parameter in the payload file represents:

Table - Payload Parameters

Parameter	Purpose	Possible Values
role	Name of the Fabric enrollment to be used.
type	Event type	transaction: concerned with events on a particular transaction ID. chaincode: returns events emitted from a chaincode. block: returns the entire data in a block. filteredtransaction: returns block number and each transaction ID along with the validation code and payload of the chaincode event.
callbackURL	Event callback address.	Must be a valid HTTP/HTTPS address.
expires	Subscribed event expire time since the time of current request.	<xx>M, <xx>w, <xx>d, <xx>h, <xx>m where: xx is a valid integer. M represents month. w is week. d is day. h is hour m indicates minute. If not set, default value is 1d, that is, one day.
callbackTLSCerts	Call back TLS Certificates.	It contains: caCert (optional): Callback server's CA certificate. It will be used by Rest Proxy to verify the callback server. The certificate must be in PEM format. clientCert (optional): Client certificate that will be used as Rest Proxy's certificate when connecting to the callback server. It is only required when the callback server enables mutual authentication. The certificate must be in PEM format and assumes the private key and the client certificate concatenated. keyPassword (optional): Encrypted private key's password. It must be base64 encoded and it is required only when the clientCert contains an encrypted private key.
txid	Transaction ID
chaincode	Chaincode ID of the chaincode application subscribed to.
seek	Which blocks to be delivered.	oldest: delivers all blocks from the oldest block newest: delivers the newest block from: delivers from the block number specified for the block parameter. This option can be used only if the type is block or filteredblock.
block	Block number	This value is used when seek is from.
event	Chaincode's event filter	* specifies all events.

Note:

You can find the restproxy value of your Blockchain instance from the Nodes tab of your instance console.

Example of the Response Body

The following example shows the contents of the response body in JSON format:

{
   "returnCode": "Success",
   "error": "",
   "result": {
       "subid": "obpuser-dc28b77c-7e58-4b09-ae23-b2c01fa01b70"
   }
}

Back to Top