5 FAQs

This section addresses common questions related to the Oracle Hospitality Integration Platform (OHIP) Streaming API, providing clarity on its usage, requirements, and best practices.

What are the minimum requirements for using the OHIP Streaming API?

To utilize the OHIP Streaming API, ensure the following prerequisites are met:

  • OPERA Cloud Version: The property must be running OPERA Cloud Foundation version 22.3.0.1 or later.
  • OHIP Subscription: Customers should have an active subscription to OPERA Cloud Foundation, which includes OHIP. Partners require a subscription to the Oracle Hospitality Integration Cloud Service.
  • Streaming API Enablement: Engage with Oracle Professional Services to enable the Streaming API for your environment.

How do I enable the Streaming API for my environment?

To enable the Streaming API for customers:

  • Initial Environment: Purchase the Oracle Hospitality Integration Platform Cloud Premium Remote Assistance SKU - 4 Hour Workshop (B93152) to engage with Oracle Professional Services. This workshop includes enabling streaming for one UAT chain.
  • Subsequent Environments: Raise a Technical Service Request (SR) with Oracle, providing details such as Customer Name, Customer Chain, Environment Name, Shared Security Domain, and EnterpriseId.

To enable the Streaming API for partners:

Raise a Technical Service Request (SR) with Oracle, providing details such as Customer Name, Customer Chain, Environment Name, Shared Security Domain, and EnterpriseId.

How long does OHIP retain events for replay purposes?

OHIP retains messages for 7 days. Events sent within this period can be replayed if necessary. Messages not consumed within 7 days are lost and cannot be replayed.

How frequently should I connect to the Streaming API to consume events?

It is recommended to maintain a continuous WebSocket connection to the Streaming API, subject to OAuth token refresh. Ensure that you connect at least every hour to prevent message loss.

What are the best practices for consuming events through the Streaming API?

To effectively consume events:

  • Single-Threaded Application: Use a single-threaded application to consume events and consider deploying tools like Apache Kafka for multi-threaded processing to backend systems.
  • Buffering Mechanism: Implement a buffering mechanism to process events before writing to the backend database, preventing potential overload.
  • Persistent Connection: Maintain a persistent connection to the Streaming API, disconnecting only when necessary (for example, to refresh the OAuth token).
  • Proper Disconnection: When disconnecting, send the "Complete" message and process any events in transit before allowing the Streaming API to close the connection.
  • Regular Ping Messages: Send a "ping" request every 15 seconds to keep the connection open.

Can multiple developers use the same application for the Streaming API?

No, each developer must use a separate application when developing against the Streaming API. The Streaming API adheres to the graphql-ws protocol, which requires that a given stream receives a connection from only one source to preserve the ordering of events. Using the same application for multiple developers can result in connection conflicts.

What should I do if I need to replay events after a disconnection?

If your application disconnects and needs to replay missed events:

  • Reconnect Promptly: Re-establish the WebSocket connection as soon as possible.
  • Use the "offset" Parameter: When reconnecting, include the offset parameter with the last received offset value to resume event replay from that point.

How do I ensure my application handles high volumes of events efficiently?

To handle high event volumes:

  • Buffer Events: Implement a buffering mechanism to manage incoming events before processing.
  • Scalable Architecture: Utilize scalable tools like Apache Kafka to distribute event processing across multiple consumers.
  • Monitor Performance: Regularly monitor your system's performance and adjust resources as needed to handle the event load.

By adhering to these guidelines and best practices, you can effectively implement and utilize the OHIP Streaming API to enhance your hospitality operations.

How much does streaming cost?

Customers do not pay for the Streaming API. Partners pay per event, with 100,000 events costing $10. In the sandbox environments, partners may incur charges from the actions of other partners using the same sandbox.

I'm used to polling. What is the biggest difference when switching to streaming?

With streaming, your app will respond to real-time events as they happen rather than ask for updates on a schedule. This is faster, avoids rate limits on polling, and puts less load on both your app and the Oracle platform, but requires you to manage a persistent connection and handle occasional reconnections. See Use Cases for a step-by-step migration path.

I'm familiar with standard WebSocket and GraphQL subs. What's unique here?

  • One consumer per stream: Only one connected client per app key/chain at a time; all others will be refused.
  • Connection URL: Must pass a SHA256 hash of your application key as a query string.
  • Manual approvals provisioning: Integration and event subscription approvals are mandatory through the Oracle Hospitality Developer Portal.
  • Replay: Offset for resuming must be supplied as a string; events are retained for 7 days.
  • Explicit closure: Send complete and wait for server close. Do not close client-side.

Can I clear the backlog of events?

Not currently, but you can skip to the latest event in the stream and continue processing from there (see Retrieving the Latest Event).

Can I connect to multiple chains at the same time with the same application key?

Yes. If the partner has configured the application's subscriptions for each chain in the Developer Portal and the customer has approved them, you can open simultaneous connections to different chains using the same appKey.

For example, connect to chain A with chain A credentials and appKey1 while also connecting to chain B with chain B credentials and the same appKey1.

The "single consumer per stream" limit still applies per appKey, chainCode, and gateway, and each connection must use an OAuth token valid for its target chain/environment.

Note on customer vs partner application scope:

  • Customer-owned applications are scoped to a single chain. To connect to multiple chains, customers must create separate applications (one per chain) under each target chain in the OHIP Developer Portal; each application will have its own app key.
  • Partner-owned applications can be used across multiple customer chains (subject to configuring subscriptions in the Developer Portal and obtaining each customer's approval), enabling concurrent connections to different chains with the same app key.

How do I avoid receiving events caused by my own REST API calls?

If your integration updates OPERA via REST and you do not want to consume the Business Events triggered by those updates, include the header below on those write requests. The external system code is shown in the OHIP Developer Portal under your Application → Events tab → Subscribed tab as "Application's external system code." For more information, see Suppressing Events from Your Own REST Calls.

x-externalSystem: <externalSystemCode>

Can a partner's application be restricted to only certain hotels within a chain?

Yes, this can be configured while approving the partner's subscription in the Developer Portal. See Working with Events in the Developer Portal in the Oracle Hospitality Integration Platform User Guide.

Does the Streaming API support ACKs or a server DLQ?

No. There is no application‑level ACK handshake and no platform‑managed dead‑letter queue. Treat "successful processing + persisted offset" (and uniqueEventId) as your acknowledgment. If an event repeatedly fails, send it to your own DLQ and continue consuming. In Performance Considerations, see "Design the Intake Path for Ordered Processing." In Scaling Recommendations, see "Implement Backpressure Handling."

Can I connect to the Streaming API directly from a mobile app or browser?

No. Just like other Oracle Hospitality APIs, the Streaming API must not be called directly from mobile apps or browser-based front ends. Use a trusted back-end for front-end service to:

  • Hold and protect secrets (credentials, OAuth tokens, application keys, hashes).
  • Establish and manage the WebSocket connection to the Streaming API (including ping/pong, reconnects, token refresh).
  • Enforce your application's authorization, masking/PII policies, and rate limits.
  • Fan-out only the minimal data needed to clients over your own secure channel.

See the Oracle Hospitality Integration Platform Security Guide.

Automation Considerations

  • Application/environment enablement and event approval cannot be performed automatically. Your scripts must consume previously provisioned credentials.
  • The Streaming API supports only a single consumer per application key and chain code; programmatically check and wait if connection is rejected with code 4409.
  • The offset retention window is 7 days; schedule automated connects accordingly.
  • Always implement idempotency and duplicate suppression through offset + uniqueEventId tracking.