9 Key Terminology

Application Key: A unique identifier generated when an application is registered in the OHIP Developer Portal, used to authenticate requests and manage access to the Streaming API.

Authorization Header: The HTTP header Authorization: Bearer Access_Token used to include the OAuth token in requests to the Streaming API.

Buffering Mechanism: A system design practice where events received from the Streaming API are temporarily stored before being processed to prevent back-end overload.

Business Event: An event representing a change or update to a resource, such as a reservation, which can be consumed by subscribing to the Streaming API.

Chain Code: An identifier representing a specific hotel chain within OPERA Cloud, used in the Streaming API to filter events pertinent to that chain.

Client ID and Client Secret: Credentials used to obtain an OAuth token for authenticating requests to the OHIP Streaming API.

Complete Message (complete): A message sent by the client to terminate a subscription and close the WebSocket connection.

Connection Acknowledgment (connection_ack): A message sent by the server in response to connection_init, indicating that the connection has been successfully established.

Connection Initialization (connection_init): A message sent by the client to initiate a WebSocket connection with the OHIP Streaming API.

Environment: A specific instance of OPERA Cloud (for example, UAT or Production) from which events are consumed through the Streaming API.

Event Acknowledgment: In this Streaming API, there is no server‑side ACK. Treat successful processing and persisting the event's offset (and uniqueEventId) as your acknowledgment.

Event Backpressure: A flow control mechanism to prevent overwhelming consumers by adjusting the rate of event delivery based on processing capacity.

Event Consistency: The assurance that all consumers have a synchronized view of event data, maintaining data integrity across systems.

Event Consumer: An application or system that subscribes to and processes events from the OHIP Streaming API.

Event Detail: The specific data within a business event, including elements like oldValue, newValue, and elementName, providing context about the change.

Event Duplication: The occurrence of receiving the same event more than once, which consumers must handle to prevent redundant processing.

Event Error Handling: The strategies implemented to manage and recover from errors encountered during event processing.

Event Filtering: The process of specifying criteria to receive only certain types of events from the Streaming API, reducing unnecessary data processing.

Event Idempotency: The property ensuring that processing the same event multiple times has no additional effect, preventing unintended side effects.

Event Latency: The time delay between the occurrence of an event in the source system and its receipt by the consumer application.

Event Logging: The recording of event-related activities and errors for auditing, debugging, and compliance purposes.

Event Monitoring: The continuous observation and analysis of event flow and processing to ensure system health and performance.

Event Name: The specific name of the event being dispatched, indicating the type of change, such as "UPDATE" or "DELETE."

Event Ordering: The sequence in which events are delivered and processed, which is crucial for maintaining data consistency in consuming applications.

Event Payload: The actual data contained within an event message, including details about the change and relevant metadata.

Event Processing: The actions taken by a consumer application upon receiving an event, such as updating records or triggering workflows.

Event Producer: The source system (for example, OPERA Cloud) that generates and dispatches events to the Streaming API.

Event Replay: The capability to retrieve past events from the Streaming API by specifying an offset, allowing clients to process missed events.

Event Resilience: The capability of the event processing system to recover from failures and continue operating effectively.

Event Retention Period: The duration for which events are stored and available for replay in the Streaming API; typically, OHIP retains messages for 7 days.

Event Scaling: The ability to handle increasing volumes of events by optimizing infrastructure and application design.

Event Schema: The defined structure and format of event data, including fields and data types, which consumers must adhere to for proper processing.

Event Security: The measures taken to protect event data during transmission and processing, including authentication, authorization, and encryption.

Event Subscription: The act of registering to receive specific events from the Streaming API based on defined criteria.

Event Subscription Approval: The process by which environment owners approve applications to consume events from their environment through the Streaming API.

Event Template: A predefined set of events that an application subscribes to in the OHIP Developer Portal, specifying which events to consume.

Event Throughput: The rate at which events are delivered and processed over a given period, impacting system performance and scalability.

Event Versioning: The practice of managing changes to event schemas over time to ensure backward compatibility and smooth transitions.

Gateway URL: The URL endpoint of the OHIP environment used to establish a WebSocket connection for the Streaming API.

GraphQL: A query language for APIs that allows clients to request specific data structures, facilitating efficient and flexible data retrieval.

GraphiQL: An open source GraphQL Integrated Development Environment (IDE), customized by Oracle Hospitality to provide a playground for becoming familiar with the Streaming API, including visualization of event schemas.

Hashed Application Key: Unlike most WebSocket providers, the OHIP Streaming API requires the SHA256 hash of your app key to be passed as a query parameter, not in a header.

Metadata: Additional information about an event, such as the offset and uniqueEventId, used for tracking and processing events.

Module Name: The name of the module within OPERA Cloud to which an event belongs, such as "Reservation" or "Profile."

Next Message (next): A message sent by the server containing the event data that matches the client's subscription criteria.

OAuth Token: An authorization token obtained using client credentials, required for authenticating requests to the OHIP Streaming API.

Oracle Hospitality Integration Platform (OHIP): A platform that facilitates integration between various hospitality systems, enabling seamless data exchange and interoperability.

Offset: A parameter used in the Streaming API to specify the starting point for consuming events, allowing clients to resume from a specific event in the stream. Text, not a number.

OffsetType: A parameter in the Streaming API that determines the starting point for event consumption; setting it to "highest" retrieves only the latest event.

Ping/Pong Messages: Heartbeat messages exchanged between the client and server to keep the WebSocket connection alive; the client sends a "ping," and the server responds with a "pong."

Poison Message: A message that repeatedly fails your business processing.

Polling: The process of repeatedly asking the server if anything new has happened since your last request (used in legacy APIs; less efficient than streaming).

Rate Limiting: The practice of controlling the number of API requests sent within a specific time frame to prevent server overload and ensure fair usage.

Single-Threaded Application: An application design recommended for consuming events through the Streaming API to maintain event order and prevent conflicts.

Streaming API: An API that allows real-time data streaming, enabling applications to receive updates as events occur without the need for continuous polling.

Subscription (subscribe): A message sent by the client to subscribe to specific events in the Streaming API, specifying parameters like chainCode and offsetType.

Throttling: A mechanism that limits the number of concurrent API calls to maintain system performance and prevent degradation of service.

WebSocket: A communication protocol that provides full-duplex communication channels over a single TCP connection, commonly used for real-time data transfer.

WebSocket Connection Timeout: The duration after which an idle WebSocket connection is closed if no activity (for example, ping/pong messages) is detected.

WebSocket Protocol Header: The header Sec-WebSocket-Protocol: graphql-transport-ws included in the WebSocket connection request to specify the subprotocol used.

By understanding these terms, you can effectively navigate and implement the OHIP Streaming API in your applications.