Connect to a Data Stream and Consume Data

Use the following steps to connect to a Data Stream and consume data:

Step 1: Build the WebSocket URL

Read the following values from the generated AsyncAPI YAML:

servers.<name>.protocol: ws or wss.
servers.<name>.host: host name and, when present, port.
channels.<name>.address: complete WebSocket path for the Data Stream.

wss://<server-host><channel-address>?begin=<percent-encoded-begin-value>

Do not hardcode the path: OCI GoldenGate, an on-premises deployment, and a reverse proxy can expose different routing prefixes. Copy the host and channel address from the generated YAML or the canonical links returned by the REST API.

Step 2: Select the begin value

Specify the BEGIN value based on the guidelines provided in the following table:

Value	Use	Guidelines
`now`	Start with new activity	Converted to the current timestamp and resolved against the available trail. Changes before the resolved point are not delivered.
`earliest`	Initial backfill from available trail	Converted to timestamp zero. Delivery starts at the earliest record still available in the configured trail, not necessarily the beginning of source history.
ISO 8601 timestamp	Start near a business time boundary	The service performs a timestamp-based lookup. Use an explicit time zone, for example `2026-07-13T04:00:00Z`.
Saved `pos`	Recovery after a prior successful run	The service performs a position-based lookup. The outcome when the position is unavailable depends on quality of service.

Percent-encode the begin value

A pos token can contain characters such as +, /, and = that have special meaning in a URL. Percent-encode the complete token before adding it to the query string. Do not modify or decode the token in application logic.

Step 3: Authentication and TLS

Select the authentication method. Use the following table to determine the most suitable method:

Mode	When to use	Client Response
Basic authentication	Common with a directly exposed service or reverse proxy	Send an `Authorization: Basic ...` header. Keep credentials in a secret store or environment injection, not in the URL or source code.
Digest authentication	When required by the reverse proxy	Use a client or generated template that implements the HTTP digest challenge during the WebSocket handshake.
Client certificate	Mutual TLS or certificate-based service authentication	Load the client certificate and private key into the TLS context and validate the server against the configured CA.
Secure reverse proxy	Gateway terminates or forwards TLS	Follow the proxy authentication mode. A secure proxy can require both basic/digest credentials and a client certificate.

Step 4: Generate a client from AsyncAPI

Oracle provides a WebSocket client template for AsyncAPI Generator. It can generate JavaScript, Python, Java, Go, or all supported clients. The generator requires Node.js 18.12 or later and npm 8.19 or later.

npm install -g @asyncapi/generator

git clone https://github.com/oracle-samples/websocket-client-template.git
cd websocket-client-template

ag /path/to/sales-orders.yaml .
  -o output
  -p server=production
  -p language=python
  -p authorization=basic

cd output
python -m pip install -r requirements.txt
export ASYNCAPI_WS_CLIENT_USERNAME="$OGG_USER"
export ASYNCAPI_WS_CLIENT_PASSWORD="$OGG_PASSWORD"
python client.py

The template also supports certificate variables ASYNCAPI_WS_CLIENT_CERT, ASYNCAPI_WS_CLIENT_KEY, and ASYNCAPI_WS_CA_CERT. Review generated code and dependency versions under your organization’s usual secure software development process.

Step 5: Understand WebSocket messages

The usual message payload is a JSON array. A frame can contain one or more schema, metadata, DML, or DDL records. The client must iterate the array and classify each object independently.

Backpressure: The service pushes records without a per-record client acknowledgment. Keep the receive loop lightweight. Put slow business processing behind a bounded internal queue or durable staging layer, monitor queue depth, and stop or scale the consumer before memory is exhausted.

Step 6: Consumer processing loop

Receive a complete WebSocket message.
Parse the JSON array. When CloudEvents is enabled, unwrap the data member.
Classify schema, stream metadata, object metadata, DML, and DDL records.
Validate records against the latest cached schema when validation is required.
Apply the business operation or publish it to a durable downstream system.
After the operation succeeds, save the record pos using the selected atomic or idempotent checkpoint design.
On connection loss, reconnect with the last durable pos and exponential backoff.