Jump to

• Request
• Response
• Examples

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.

Back to Top

Response

Supported Media Types

• application/json

200 Response

Successful operation

Body ()

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

Headers

• opc-request-id: string
  Unique Oracle-assigned identifier for the request. If you need to contact Oracle about a particular request, please provide the request ID.

Body ()

Root Schema : Error

Type: object

Error Information.

Show Source

• code(required): string
  A short error code that defines the error, meant for programmatic parsing.
• message(required): string
  A human-readable error string.

{
    "description":"Error Information.",
    "required":[
        "code",
        "message"
    ],
    "properties":{
        "code":{
            "description":"A short error code that defines the error, meant for programmatic parsing.",
            "type":"string"
        },
        "message":{
            "description":"A human-readable error string.",
            "type":"string"
        }
    }
}

401 Response

Unauthorized

Headers

• opc-request-id: string
  Unique Oracle-assigned identifier for the request. If you need to contact Oracle about a particular request, please provide the request ID.

Body ()

Root Schema : Error

Type: object

Error Information.

Show Source

• code(required): string
  A short error code that defines the error, meant for programmatic parsing.
• message(required): string
  A human-readable error string.

{
    "description":"Error Information.",
    "required":[
        "code",
        "message"
    ],
    "properties":{
        "code":{
            "description":"A short error code that defines the error, meant for programmatic parsing.",
            "type":"string"
        },
        "message":{
            "description":"A human-readable error string.",
            "type":"string"
        }
    }
}

403 Response

Forbidden

404 Response

Not Found

Headers

• opc-request-id: string
  Unique Oracle-assigned identifier for the request. If you need to contact Oracle about a particular request, please provide the request ID.

Body ()

Root Schema : Error

Type: object

Error Information.

Show Source

• code(required): string
  A short error code that defines the error, meant for programmatic parsing.
• message(required): string
  A human-readable error string.

{
    "description":"Error Information.",
    "required":[
        "code",
        "message"
    ],
    "properties":{
        "code":{
            "description":"A short error code that defines the error, meant for programmatic parsing.",
            "type":"string"
        },
        "message":{
            "description":"A human-readable error string.",
            "type":"string"
        }
    }
}

500 Response

Internal Server Error

Headers

• opc-request-id: string
  Unique Oracle-assigned identifier for the request. If you need to contact Oracle about a particular request, please provide the request ID.

Body ()

Root Schema : Error

Type: object

Error Information.

Show Source

• code(required): string
  A short error code that defines the error, meant for programmatic parsing.
• message(required): string
  A human-readable error string.

{
    "description":"Error Information.",
    "required":[
        "code",
        "message"
    ],
    "properties":{
        "code":{
            "description":"A short error code that defines the error, meant for programmatic parsing.",
            "type":"string"
        },
        "message":{
            "description":"A human-readable error string.",
            "type":"string"
        }
    }
}

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 -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>" \
  -H "Authorization: Bearer <OAuth_access_ token>"

For example,

curl -v -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" \
  -H "Authorization: Bearer mF_9.B5f-4.1JqM"

Note:

You can find the REST proxy value of your 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