REST API for Oracle Blockchain Platform Enterprise Edition

List Event Subscriptions

get

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

List all event subscriptions

Request

Supported Media Types

application/json

Path Parameters

channelId: string

ID of the channel

Query Parameters

role: string

Name of Fabric enrollment to be used
subscription-id: string

ID of the subscription when operation succeeds
user-id: string

User name. It should be the same user defined in basic auth.

Response

Supported Media Types

application/json

200 Response

Successful operation

Root Schema : schema

Type: object

Show Source

error(optional): string

Default Value:

Error message when operation fails
result(optional): array 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":"array",
            "items":{
                "$ref":"#/definitions/EventSubscription"
            }
        }
    }
}

Nested Schema : result

Type: array

Show Source

Array of: object EventSubscription

{
    "type":"array",
    "items":{
        "$ref":"#/definitions/EventSubscription"
    }
}

Nested 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"
        }
    }
}

400 Response

Bad Request

401 Response

Not authorized

403 Response

Forbidden

404 Response

Invalid parameters

500 Response

Service unavailable

Examples

This endpoint is used to generate a list of all the events subscribed by a Blockchain user in the specified channel.

The following example shows how to get the list of event subscriptions by submitting a GET request on the REST resource using cURL.

curl -v -u <username>:<password> -X GET \
  "<restproxy of your Blockchain instance>/api/v2/channels/default/event-subscriptions?role=<role>&user-id=<username>&subscription-id=<subscription ID>&channelId=<channel ID>"

For example,

curl -v -u obpuser:<password> -X GET \
  "https://myvm.oracle.com:10001/restproxy/api/v2/channels/default/event-subscriptions?role=myinstance_defaultuser&user-id=obpuser&subscription-id=obpuser-dc28b77c-7e58-4b09-ae23-b2c01fa01b70&channelId=default"

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-b75db132-605a-41a1-86d2-d5be9237c826",
       "type": "chaincode",
       "callbackURL": "http://10.168.108.17:9000",
       "callbackTLSCerts": {},
       "expires": "1m",
       "expireTime": "2019-08-20T04:33:53+0000",
       "txid": "b1c11242383212cfdcca97d68efc0b3641436b1845a9b4c6e822cf6099ca49ee",
       "chaincode": "obcs-example02",
       "event": ".*",
       "seek": "newest",
       "block": 0
   }
}

Where:

subid is the subscription ID.
type specifies the event type. In this example, chaincode indicates that the events emitted from a chaincode will be returned.
callbackURL specifies the event callback address which is a valid HTTP/HTTPS address.
expires indicates that this subscription expires after 1 month since the time of current request.
txid is the transaction ID.
chaincode is the chaincode ID of the chaincode application subscribed to.
event is the chaincode event filter. * indicates that the user subscribed to all the events in the specified chaincode.
seek specifies which blocks to be delivered. In this example, newest indicates that this subscription delivers the newest block.
block indicates the block number.