REST API for Oracle Blockchain Platform on Oracle Cloud Infrastructure

Subscribe to an Event

post

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

Subscribe to an event.

Request

Supported Media Types

application/json

Path Parameters

channelName(required): string

ID of the channel

Request to subscribe to an event

Root Schema : EventSubscription

Type: object

Show Source

block: integer(int64)

Number of the block
callbackTLSCerts: object callbackTLSCerts
callbackURL(required): string

URL to callback
chaincode: string

Name of the chaincode
event: string

Name of the event
expires: string

Expiration of the subscription
maxCallbackRetry: integer

Maximum number of retries. The 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

Specifies 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(required): string

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

Event type to subscribe to

{
    "type":"object",
    "required":[
        "type",
        "callbackURL"
    ],
    "properties":{
        "role":{
            "description":"Specifies 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. The 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":"Name of the chaincode",
            "type":"string"
        },
        "event":{
            "description":"Name of the event",
            "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 in case of client credential flow and can be provided optionally in refresh token flow as well",
                    "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

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 have to be passed in the header.
clientID: string

The client ID for the Oauth application. It is required in case of client credential flow and can be provided optionally in refresh token flow as well
clientSecret: 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: string

Generate and pass the refresh token if using 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 access token will 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 in case of client credential flow and can be provided optionally in refresh token flow as well",
            "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"
    }
}

Response

Supported Media Types

application/json

200 Response

Operation successful

Root Schema : schema

Type: object

Show Source

error: string

Default Value:

Error message when operation fails
result: object 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":"object",
            "required":[
                "subid"
            ],
            "properties":{
                "subid":{
                    "description":"ID of the subscription when operation succeeds",
                    "type":"string"
                }
            }
        }
    }
}

Nested Schema : result

Type: object

Show Source

subid(required): 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

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.

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.

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.

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.

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

Examples

This endpoint is used to request an event subscription.

Invoking Callback Endpoints with TLS Certs

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

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

Example request:

curl -v -X POST \
  "https://myvm.oracle.com:10000/restproxy/api/v2/channels/default/event-subscriptions" \
  -H "Authorization: Bearer mF_9.B5f-4.1JqM" \
  -H "accept: application/json" \
  -H "Content-Type: application/json" \
  --data @file.json

The file.json file has the following contents:

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

The parameters in the payload file represent the following values:

Table - Payload Parameters

Parameter	Purpose	Possible Values
`role`	Name of the Fabric enrollment to use.
`type`	Event type.	`transaction`: returns events for a specific transaction ID. `chaincode`: returns events emitted from a chaincode. `block`: returns all of the data in a block. `filteredblock`: 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.
`maxCallbackRetry`	This parameter specifies how many times to retry the call until event delivery succeeds or until the REST proxy restarts. The retry interval will exponentially increase, starting at 1 second and increasing to 120 seconds. An HTTP 4XX response (excluding HTTP 401 and HTTP 429) will override this value, as those responses are considered to be terminal failures. The system will log that particular event as a failure and proceed with any remaining events in the queue.	Must be an integer. Represents the number of times to retry after the initial call. The default is 7.
`expires`	Subscribed event expiration time since the time of current request.	`<xx>M`, `<xx>w`, `<xx>d`, `<xx>h`, `<xx>m` The variables in the example have the following values: `xx` is a valid integer. `M` represents months. `w` is weeks. `d` is days. `h` is hours `m` indicates minutes. If not set, the default value is `1d`; that is, one day.
`callbackTLSCerts`	Callback TLS certificates.	This parameter contains the following values: `caCert` (optional): Callback server's CA certificate. It is used by the REST proxy to verify the callback server. The certificate must be in PEM format. `clientCert` (optional): Client certificate to use as the REST proxy's certificate when connecting to the callback server. It is required only when the callback server enables mutual authentication. The certificate must be in PEM format, and assumes that the private key and the client certificate are concatenated. `keyPassword` (optional): Encrypted private key's password. It must be base64 encoded and it is required only when the `clientCert` certificate contains an encrypted private key.
`txid`	Transaction ID.
`chaincode`	Chaincode ID of the chaincode application to subscribe to.
`seek`	Specifies which blocks to deliver.	`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 for all `type`parameters except for the `transaction` type.
`block`	Block number.	This value is used when the `seek` parameter is set to `from`.
`event`	Chaincode's event filter.	Use an asterisk (`*`) to specify all events.

Note:

You can find the REST proxy value of your instance on the Nodes page of the instance console.

The maximum payload size of an event is limited to 50 KB. Any events larger than the maximum payload size will be dropped. The Oracle DevOps team can modify this parameter by request. If you expect to subscribe to events where the payload will be larger than 50 KB, open a Service Request (SR) in Oracle Support to request a larger maximum event size.

Invoking Callback Endpoints Secured with OAuth 2.0

You can invoke callback endpoints secured with OAuth 2.0. In this case you pass the oauth parameter instead of the callbackTLSCerts parameter. The following example shows a payload file for event subscription using OAuth 2.0 tokens:

{
  "type": "block",
  "callbackURL": "192.0.2.1",
  "callbackTLSCerts": {},
  "expires": "30m",
  "seek": "newest",
  "event": ".*",
  "maxCallbackRetry": 7,
  "oauth": {
      "clientID": "my-client-id",
      "clientSecret": "my-client-secret",
      "tokenUrl": "https://identity.example.com/oauth2/v1/token",
      "authInHeader": true,
      "scopes": ["urn:opc:idm:__myscopes__"]
  }
}

The variables in the example have the following values:

type specifies the event type. In this example, block indicates that the data from a block will be returned.
callbackURL specifies the event callback address, which is a valid HTTP/HTTPS address.
expires indicates that this subscription expires after 30 minutes since the time of current request.
seek specifies which blocks to deliver. In this example, newest indicates that this subscription delivers the newest block. This option can be used for all type parameters except the transaction type.
event is the chaincode event filter. An asterisk (*) indicates that the user subscribes to all events in the specified chaincode.
maxCallbackRetry specifies the number of times event delivery is attempted until it succeeds. The default value of the maxCallbackRetry parameter is 7.

The oauth parameter contains the following parameters:

Table - OAuth Parameters

Parameter	Purpose
`clientID`	The client ID. Required when using client credentials. Optional when refreshing an expired token.
`clientSecret`	The client secret. Required when using client credentials. Optional when refreshing an expired token.
`refreshToken`	The refresh token. Required when refreshing the use of an access token that has expired.
`tokenUrl`	The URL to use to obtain tokens. This parameter is always required.
`scopes`	A list of scopes to associate with the token.
`authInHeader`	A Boolean value indicating how the credentials will be passed. If true, the credentials will be passed in the header. If false, the credentials will be passed in the payload.

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

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