Streaming APIs

Table 18-3 Streaming

Best Practice	What to avoid and why
Use a single-threaded application to consume events through the Streaming API, and then deploy a tool like Apache Kafka and multi-threaded clients to consume events from Apache Kafka to populate backend systems. While we recommend using our GraphiQL tool or using Postman to solidify understanding of the Streaming API, it is important to use separate applications for GraphiQL, Postman, and your client code. Similarly, your client code must be single threaded. For an example, refer to the Spring Boot documentation. Use a single WebSocketGraphQlClient instance for each server to have a single, shared connection for all requests to that server. Each client instance establishes its own connection, which is typically not the intent for a single server.	Calling the streaming API through a multi-threaded consumer. 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. A stream is identified as a combination of the following: gateway + the chainCode + an application key.
Implement a buffering mechanism such that events received from the streaming API are consumed from the buffer before being written to the back-end database.	Writing straight to back-end database after receiving an event from the streaming API. OPERA Cloud can generate many thousands of events in certain circumstances, and the Streaming API is not throttled. If the streaming client is coded to write straight to a back-end database, this can overwhelm the back-end database.
Stay connected to the Streaming API and only disconnect when you must refresh the oAuth token. If you leave more than 24 hours between connecting, you must send the "offset" input parameter together with the value of the last offset you received when reconnecting.	Connecting and then disconnecting frequently from the Streaming API, or connecting only intermittently. The Streaming API is built upon WebSocket, where the connection remains open. Barring network events, it is expected that the WebSocket connections will remain open and connected permanently to the Streaming API, subject to the lifetime of the oAuth token. For best practices on oAuth tokens, see Property APIs. Disconnecting and reconnecting after a period of time can lead to a significant backlog of events, making it difficult for the consuming architecture to process them efficiently.
When disconnecting from the Streaming API, it is important to follow the protocol and send the "Complete" message. You must accept and process any events in the process of being sent, but wait for OHIP to close the connection. Consuming systems must wait 500ms before reconnecting.	Disconnecting incorrectly from the Streaming API (for example, simply closing the connection). This can cause the WebSocket not to reopen. Not accepting and processing events in the process of being sent after sending a Complete message results in lost events and the need to replay.
Ensure architecture consuming the Streaming API sends the “ping” request every 15 seconds. This is not billable. For more information, see Keeping the Stream Open.	Not sending the “ping” request to the Streaming API, or not sending it frequently enough will result in the connection automatically being closed after 30 seconds.
Use the “offset” request parameter for the Streaming API only in a replay scenario. For more information, see Replaying Messages. In every other scenario, remain connected to the Streaming API and after obtaining an oAuth token, connect without specifying an offset. OHIP will resume sending events starting from the next offset.	Disconnecting and then reconnecting from the Streaming API, starting from a given offset, or starting from the last received offset plus one. Each business event sent on the streaming API is given a different offset number. While these appear to increment, a linear progression is not guaranteed. The offset number also changes if the consumer has been disconnected from the stream for over 24 hours. Making assumptions about the offset can result in a failure to connect. Not remaining connected can result in a large backlog of events that may never be consumed.
Use different applications created in the OHIP Developer Portal when developing against the Streaming API.	All developers using the same application for 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. A stream is identified as a combination of the following: gateway + the chainCode + an application key. If two developers are trying to use the same application to access the Streaming API, they will lock each other out.
Ensure there is a minimum of 10000 ms (10 seconds) between sending the "complete" message to close one WebSocket connection and the next "subscribe" message to reopen a WebSocket connection.	Send the "complete" message and then very quickly send a new "subscribe" message. Reconnecting too quickly risks locking the connection.
Use the OHIP developer portal to subscribe to consume events through the Streaming API only when the consuming architecture is ready.	Enabling business events ahead of being ready to consume. As soon as an application is subscribed to business events in OPERA, the subscribed events will start to be enqueued. If not consumed, this will result in a large queue, which is challenging for consuming systems to process. Further, if the integration sends responses back to OPERA Cloud as a result of events received and is slow to process the events, then the operational impact can occur as the state of the data in OPERA Cloud would differ from the state of the data perceived by an integration that is running behind.