Jump to

• Request
• Response
• Examples

List Event Subscriptions

get

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

List all event subscriptions.

Request

Supported Media Types

• application/json

Path Parameters

• channelName: string
  ID of the channel

Query Parameters

• role: string
  Name of the Hyperledger Fabric enrollment to be used
• subscription-id: string
  ID of the subscription when successful
• user-id: string
  User's name. It should be the same user defined in basic auth.

Back to Top

Response

Supported Media Types

• application/json

200 Response

Successful operation

Body ()

Root Schema : schema

Type: object

Show Source

• error(optional): string
  Default Value:

  Error message when request 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 request 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(optional): object callbackTLSCerts
  TLS certificate information
• callbackURL: string
  URL to callback
• chaincode(optional): string
  Chaincode name
• event(optional): string
  Event name
• expires(optional): string
  Expiration of the subscription
• maxCallbackRetry(optional): integer
  Maximum number of retries. Retry interval grows based on exponential backoff to a maximum of 2 minutes.
• oauth(optional): object oauth
  Provide details of the OAuth application if the callback server is OAuth2 protected. Only client credential and refresh token flows are supported.
• role(optional): string
  Which Hyperledger Fabric enrollment should be used
• seek(optional): string
  Allowed Values: [ "oldest", "newest", "from" ]

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

  Event type to subscribe

{
    "type":"object",
    "required":[
        "type",
        "callbackURL"
    ],
    "properties":{
        "role":{
            "description":"Which Hyperledger Fabric enrollment should be used",
            "type":"string"
        },
        "type":{
            "description":"Event type to subscribe",
            "type":"string",
            "enum":[
                "block",
                "filteredblock",
                "transaction",
                "chaincode"
            ]
        },
        "callbackURL":{
            "description":"URL to callback",
            "type":"string"
        },
        "callbackTLSCerts":{
            "description":"TLS certificate information",
            "type":"object",
            "properties":{
                "caCert":{
                    "description":"The certificate authority certificate.",
                    "type":"string"
                },
                "clientCert":{
                    "description":"The client certificate.",
                    "type":"string"
                },
                "keyPassword":{
                    "description":"Passphrase used to access the private key.",
                    "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 \"chaincode\", \"block\" and \"filteredblock\"",
            "type":"string",
            "enum":[
                "oldest",
                "newest",
                "from"
            ]
        },
        "block":{
            "description":"Number of the block",
            "type":"integer",
            "format":"int64"
        },
        "oauth":{
            "description":"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"
                },
                "clientSecret":{
                    "description":"The client secret for the OAuth application. It is required for a client credential flow, and is optional in a refresh token flow.",
                    "type":"string"
                },
                "refreshToken":{
                    "description":"Generate and pass the refresh token if using a refresh token flow.",
                    "type":"string"
                },
                "tokenUrl":{
                    "description":"The URL against which the call for generating access token will 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 have to be passed in the header.",
                    "type":"boolean"
                }
            }
        }
    }
}

Nested Schema : callbackTLSCerts

Type: object

TLS certificate information

Show Source

• caCert(optional): string
  The certificate authority certificate.
• clientCert(optional): string
  The client certificate.
• keyPassword(optional): string
  Passphrase used to access the private key.

{
    "description":"TLS certificate information",
    "type":"object",
    "properties":{
        "caCert":{
            "description":"The certificate authority certificate.",
            "type":"string"
        },
        "clientCert":{
            "description":"The client certificate.",
            "type":"string"
        },
        "keyPassword":{
            "description":"Passphrase used to access the private key.",
            "type":"string"
        }
    }
}

Nested Schema : oauth

Type: object

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(optional): boolean
  Set to true if the authorization parameters have to be passed in the header.
• clientID(optional): string
  The client ID for the OAuth application. It is required for a client credential flow and is optional for a refresh token flow.
• clientSecret(optional): string
  The client secret for the OAuth application. It is required for a client credential flow, and is optional in a refresh token flow.
• refreshToken(optional): string
  Generate and pass the refresh token if using a refresh token flow.
• scopes(optional): array scopes
  List of scopes to be associated with the token.
• tokenUrl(optional): string
  The URL against which the call for generating access token will be made.

{
    "description":"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"
        },
        "clientSecret":{
            "description":"The client secret for the OAuth application. It is required for a client credential flow, and is optional in a refresh token flow.",
            "type":"string"
        },
        "refreshToken":{
            "description":"Generate and pass the refresh token if using a refresh token flow.",
            "type":"string"
        },
        "tokenUrl":{
            "description":"The URL against which the call for generating access token will 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 have to 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

Back to Top

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.

Back to Top