Oracle Hospitality Integration Platform’s latest release delivers a Streaming API that provides a revolutionary way to consume business events from OPERA Cloud and, in the future, other Hospitality Cloud applications. Join us in this post as we explore our Event Driven API Strategy that led OHIP to build the API using GraphQL Subscriptions and WebSockets, allowing OHIP to deliver events to you and reducing the need for continuous polling.
Event Driven API Strategy
Many factors were taken into consideration for the design and development of the Streaming API, but two of our top priorities were to ensure that the new API was consumer friendly and easy to use. Another important point is that the clients will be requesting particular events, meaning it makes sense to ensure that our implementation can be driven by the client going forward.
With our priorities set and requirements determined, the biggest design decision OHIP faced was on our Event Driven API Strategy – if you search for this topic there are a number of frameworks and network protocols such as GraphQL, Server Sent Events, WebHooks and WebSockets. Each variation has its own set of advantages and disadvantages, but we determined which strategy best suited our use-case.
We also had to consider who will be receiving the events from our API—in the sense what type of application, is it HTTP/1.1 or HTTP/2? Is it new or old? OHIP gives developers complete freedom to create any type of application, meaning that we simply do not know the answers to these questions. It was therefore critical that our streaming API must be able to support any application, whether it’s a server application, mobile device, a secure application hidden behind firewalls, or even a 20-year-old monolith hiding in a basement.
With these points top of mind, we evaluated the following approaches and scored them against our requirements:
- Server Sent Events
- WebHooks
- WebSockets
- GraphQL Subscriptions
Server Sent Events
Server Sent Events (SSE) is specification that allows a read-only stream where a server can push events to a client. The client sends an initial HTTP request, which is handled and then the connection is kept open by the server in order to emit the events. Server Sent Events are supported in newer browsers, but there are many polyfill API examples to bring SSE to older browsers.
One of the only downsides to SSE is that the default browser API that initiates a connection doesn’t allow you to provide a payload, meaning that any authentication must be provided via query strings, potentially exposing secure data and, in some cases, it could even breach the maximum URL length depending on the query parameter values.
Diagram depicting Server Sent Events (SSE) integration in a streaming technology setup. It illustrates a consuming application with a browser app, which establishes a new EventSource to an API exposure point. The API exposure uses a long-lived HTTP connection to send events to the consuming application. The SSE server is connected to a service that interfaces with a message hub and storage components.WebHooks
A WebHook acts as a callback that can be registered by the client, providing the URL of the service that should be called when an event is generated, often secured by various forms of authentication.
While this works in many use-cases (and, arguably, the most-common implementation), it requires the client to have a HTTP endpoint that can receive our events. However, as mentioned earlier, OHIP could generate events for many types of applications meaning that we cannot expect our clients to have available endpoints.
Diagram depicting WebHooks streaming technology. The diagram shows a consuming application with server app capabilities, managing HTTP POST calls to a callback URL. API exposure is shown with inbound and outbound processes, including a subscriber capability connected to a subscribers database, a message hub, and a callback capability.WebSockets
The WebSocket protocol provides two-way communication between the client and the server; in order to create this duplex connection, the client has to send a HTTP connection request (Handshake) that is upgraded to establish a WebSocket that is able to communicate over a single TCP connection. You will often find WebSockets in messaging applications such as Slack.
In 2021, WebSockets are supported by all major browsers, and there are hundreds of libraries across many programming languages that allow developers to create WebSocket connections.
OHIP’s use-case is to stream events from the server to the client; while a WebSocket offers bi-directional communication there would be little to no communication from the client to the server as OHIP will be the source of the events. The only client communication expected would be in terms of authentication and connection pings/pongs.
Illustration of WebSockets technology showing a full-duplex communication channel between a consuming application and a WebSocket server. The API exposure via WebSocket is detailed, with arrows indicating the flow of WebSocket frames to and from the service, message hub, and storage.GraphQL Subscriptions
A GraphQL Subscription offers the benefits of GraphQL for a continuous stream of data, but the actual underlying transport protocol is up to the server to implement – meaning it could be backed, for example, by Server Sent Events or WebSockets.
The client has to establish a subscription by sending a GraphQL request to the server. This request ensures the subscription is client-driven as the client can decide what data they want to receive from an event; once established, the subscription is a read-only stream of events emitted from the Server.
Diagram of GraphQL Subscriptions used in streaming technology. Two consuming applications are displayed, with one handling subscriptions and the other handling mutations. The API exposure layer involves subscription and mutation resolvers, a pub/sub system, and interfaces with various services like REST, gRPC, and SOAP, as well as a legacy system. A database is also shown connected to the GraphQL service.Comparison
Oracle offers a complete range of services to support your data warehouse, from on premises to private cloud to public cloud.
Type | Easy to Use | Client Driven | Application / Browser Support | Security |
|---|---|---|---|---|
| Server Sent Events | ++ | + | + | – |
| WebHooks | ++ | + | — | — |
| WebSockets | + | + | ++ | – |
| GraphQL Subscriptions | – | ++ | ++ | ++ |
As you can see from the table, Server-Sent Events, WebSockets, and GraphQL Subscriptions all scored highly. However, GraphQL Subscriptions provide the client with flexibility that’s unmatched. With this in mind, we chose GraphQL Subscriptions as our Event Driven API Strategy for OHIP.
After deciding upon GraphQL Subscriptions, we were then left with an implementation decision of WebSockets vs. Server Sent Events (our two top scorers). Ultimately, both fit our requirements extremely well. However, OHIP is emitting data to many applications, both new and old. With this in mind, it was a logical choice to use a technology that works out of the box in Internet Explorer and keeps it easy for clients to consume. If we were able to mandate that only new modern HTTP/2 applications could receive events from OHIP, then SSE would have been a viable option.
GraphQL Subscriptions and WebSocket Protocols
While GraphQL is heavily documented, documentation specifically for GraphQL Subscriptions is harder to come across despite being introduced more than five years ago. In short, a GraphQL Subscription is an operation that allows the server to push data to the client making it a perfect fit for OHIP.
As mentioned above, GraphQL Subscriptions can be implemented on the Server in a variety of ways, however, OHIP decided to use a popular GraphQL WebSocket protocol, Graphql-WS.
Originally, the leading GraphQL WebSocket protocol was a library created by Apollo named subscriptions-transport-ws. But as of 2021, it’s no longer maintained, and they recommend the use of GraphQL-WS instead.
GraphQL-WS is widely becoming the go-to WebSocket protocol for Subscriptions, and it’s not just in the JavaScript world. You can read the documentation for Spring GraphQL, which mentions that they also use the graphql-ws protocol for their Subscription handling.
The Graphql-WS Recipes page includes a substantial list of code examples for client usage covering a variety of concepts.
Wrap-up
Implementing an Event Driven API Strategy is a complex decision that requires taking into account a significant number of factors. This post covers some strategies at a high-level and include our thoughts and opinions in the context of the Oracle Hospitality Integration Platform.