REST API for Oracle Blockchain Platform Enterprise Edition

List Event Subscriptions

get

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

List all event subscriptions. This endpoint is used to generate a list of all the events subscribed to by a blockchain user in the specified channel.

Request

Supported Media Types

application/json

Path Parameters

channelName(required): string

ID of the channel

Query Parameters

role: string

Name of Hyperledger 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: string

Default Value:

Error message when operation fails
result: array result
returnCode(required): 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/EventSubscriptionQuery"
            }
        }
    }
}

Nested Schema : result

Type: array

Show Source

Array of: object EventSubscriptionQuery

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

Nested Schema : EventSubscriptionQuery

Type: object

Show Source

block: integer(int64)

Number of the block
callbackTLSCerts: object callbackTLSCerts
callbackURL: string

URL to callback
chaincode: string

Chaincode name
event: string

Event name
expires: string

Expiration of the subscription
maxCallbackRetry: integer

Maximum number of retries. Retry interval grows based on exponential backoff to a maximum of 2 minutes.
oauth: object oauth

Optionally provide details of the OAuth application, if the callback server is OAuth2 protected. Only client credential and refresh token flows are supported.
role: string

Which Hyperledger Fabric enrollment should be used
seek: string

Allowed Values: [ "oldest", "newest", "from" ]

Start postion of the event, only be used for type "block" and "filteredblock"
txid: string

ID of the transaction
type: string

Allowed Values: [ "block", "filteredblock", "transaction", "chaincode" ]

Event type to subscribe to

{
    "type":"object",
    "properties":{
        "role":{
            "description":"Which Hyperledger Fabric enrollment should be used",
            "type":"string"
        },
        "type":{
            "description":"Event type to subscribe to",
            "type":"string",
            "enum":[
                "block",
                "filteredblock",
                "transaction",
                "chaincode"
            ]
        },
        "callbackURL":{
            "description":"URL to callback",
            "type":"string"
        },
        "callbackTLSCerts":{
            "type":"object",
            "properties":{
                "caCert":{
                    "type":"string"
                },
                "clientCert":{
                    "type":"string"
                },
                "keyPassword":{
                    "type":"string"
                }
            }
        },
        "expires":{
            "description":"Expiration of the subscription",
            "type":"string"
        },
        "maxCallbackRetry":{
            "description":"Maximum number of retries. Retry interval grows based on exponential backoff to a maximum of 2 minutes.",
            "type":"integer"
        },
        "txid":{
            "description":"ID of the transaction",
            "type":"string"
        },
        "chaincode":{
            "description":"Chaincode name",
            "type":"string"
        },
        "event":{
            "description":"Event name",
            "type":"string"
        },
        "seek":{
            "description":"Start postion of the event, only be used for type \"block\" and \"filteredblock\"",
            "type":"string",
            "enum":[
                "oldest",
                "newest",
                "from"
            ]
        },
        "block":{
            "description":"Number of the block",
            "type":"integer",
            "format":"int64"
        },
        "oauth":{
            "description":"Optionally provide details of the OAuth application, if the callback server is OAuth2 protected. Only client credential and refresh token flows are supported.",
            "type":"object",
            "properties":{
                "clientID":{
                    "description":"The client ID for the OAuth application. It is required for a client credential flow and is optional for a refresh token flow.",
                    "type":"string"
                },
                "tokenUrl":{
                    "description":"The URL against which the call for generating an access token would be made.",
                    "type":"string"
                },
                "scopes":{
                    "description":"List of scopes to be associated with the token",
                    "type":"array",
                    "items":{
                        "type":"string"
                    }
                },
                "authInHeader":{
                    "description":"Set to true if the authorization parameters must be passed in the header.",
                    "type":"boolean"
                }
            }
        }
    }
}

Nested Schema : callbackTLSCerts

Type: object

Show Source

caCert: string
clientCert: string
keyPassword: string

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

Nested Schema : oauth

Type: object

Optionally provide details of the OAuth application, if the callback server is OAuth2 protected. Only client credential and refresh token flows are supported.

Show Source

authInHeader: boolean

Set to true if the authorization parameters must be passed in the header.
clientID: string

The client ID for the OAuth application. It is required for a client credential flow and is optional for a refresh token flow.
scopes: array scopes

List of scopes to be associated with the token
tokenUrl: string

The URL against which the call for generating an access token would be made.

{
    "description":"Optionally provide details of the OAuth application, if the callback server is OAuth2 protected. Only client credential and refresh token flows are supported.",
    "type":"object",
    "properties":{
        "clientID":{
            "description":"The client ID for the OAuth application. It is required for a client credential flow and is optional for a refresh token flow.",
            "type":"string"
        },
        "tokenUrl":{
            "description":"The URL against which the call for generating an access token would be made.",
            "type":"string"
        },
        "scopes":{
            "description":"List of scopes to be associated with the token",
            "type":"array",
            "items":{
                "type":"string"
            }
        },
        "authInHeader":{
            "description":"Set to true if the authorization parameters must be passed in the header.",
            "type":"boolean"
        }
    }
}

Nested Schema : scopes

Type: array

List of scopes to be associated with the token

Show Source

Array of: string

{
    "description":"List of scopes to be associated with the token",
    "type":"array",
    "items":{
        "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/<channelName>/event-subscriptions?role=<role>&user-id=<username>&subscription-id=<subscription ID>&channelName=<channel_name>"

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&channelName=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": "2021-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. This option can be used for all parameter type except transaction.
block indicates the block number.