1. User Guide
  2. Business Events
  3. Streaming API (push)
  4. Connecting to the Streaming API
  5. Connecting to the Streaming API with Postman

Connecting to the Streaming API with Postman

Postman can be accessed online or from the Postman API Client https://www.postman.com/product/api-client/. You must be signed in to a Postman workspace to use WebSocket APIs in Postman.

Note:

While it is possible to support WebSocket via Postman, it is not yet possible to save WebSocket requests in Postman except while signed in to a Postman workspace.

You can connect to a given stream from only one application and thread at a time. Ensure the stream (identified by the application key, URL, and chainCode) is not being used by any other applications.

Postman does not support the sending of a ping, so any postman connection closes after 5 minutes.

Consuming Events in Postman

To consume events in Postman, follow one of the two options below:

Option A

  1. Fork this Postman collection and fork this Postman environment file.

  2. Use this oAuth API example to first obtain an oAuth token.

Option B

  1. Select New and then select WebSocket Request.

  2. Enter the URL in the following format: wss://www.oracle.com/subscriptions (as described in ‘Information required to call the WebSocket’).

  3. Add the query parameter (see the ‘Query Parameters’ section).

  4. Add the headers (see the ‘Headers’ section).

  5. Send the Authentication message.

  6. Send the subscription message within 10 seconds of the Authentication message.

  7. View the events returned.

Query Parameters

The GraphQL subscription resource has one mandatory query parameter named "key." The value is a sha256 hash of the application key obtained from Registering an Application.

If LINUX environments are running, echo-n ABC-123 | sha256sum (where "ABC-123" is the application key) will return the required hash. In Microsoft Windows environments, use a code snippet or download GitBash or Windows Subsystem for Linux. To run this command, visit the Install WSL page on the Microsoft website at https://docs.microsoft.com/en-us/windows/wsl/install. Alternatively, you can use an online sha256 hash generator.

Note:

Ensure only lowercase hashes are used.

To add this to Postman:

  1. In Postman, click the Params tab

  2. In the first column, enter the value "key."

  3. In the second column, enter the value of the 256 hash that was calculated above.

Headers

The Oracle Hospitality streaming API uses the GraphQL-WS protcol passed in headers:

  1. In Postman, click the Headers tab.

  2. In the first column. enter the value "Sec-WebSocket-Protocol."

  3. In the second column, enter the value "graphql-transport-ws."

ID

All messages, except the "ping" message (see Keeping the Stream Open), require you to specify an ID in the request payload.

The ID should be a GUID to avoid collision with other consumers.

The same ID value must be used throughout a stream's life.

Authentication Message

Send the authentication "Connection Initialization" message before sending the subscription message.

  1. In Postman, click the area marked New Message and enter the following: 

{
  "id": "<GUID>"
  "type": "connection_init",
  "payload": {
      "Authorization": "Bearer <OAUTH TOKEN>
      "x-app-key": "<APPLICATION KEY>"
   }
}
Where: Once the authentication message is successfully received, the following "Connection Acknowledged" message is returned: 
{
   "type": "connection_ack",
   "payload": {
         "applicationName":"<APPLICATION NAME>"
   }
}

Where APPLICATION NAME is the name of the application that corresponds to the application key. This validates that the correct application is being used.

In Postman, the connection will show as "CONNECTED."

Subscription Message

  1. Send the subscription message within the next 10 seconds now that the connection is authenticated and connected.

  2. In Postman, overwrite the Authentication message request body with the following request body:

    {
   "id": "<GUID>",
   "type": "subscribe",   
   "payload": {       
       "variables": {},        
       "extensions": {},       
       "operationName": null,        
       "query": "subscription { newEvent(input: { chainCode: \"OHIPCN\" }) { metadata { offset } moduleName eventName detail { oldValue newValue elementName } } }"   
    }
}

    The "query" is the GraphQL query formatted against the OHIP schema. It contains the fields to be returned along with business events.

    For the full schema of what can be sent in the Subscribe request body, consult the Documentation navigator in GraphiQL.

  3. For the chainCode, specify the "tenant" entered when creating the integration user. Refer to step 1 in Authenticating to Oracle Hospitality Property APIs. This is also prefixed on your integration username.

  4. Click the Send button.

Viewing the Events Returned

In Postman, messages from the server begin with a down arrow.

To see the JSON response payload:

  1. Click to expand the message.

The payload includes only those elements from the "query" specified in the Subscription message.

When multiple events are pending subscription, each event is returned in sequence.

Parent topic: Connecting to the Streaming API