How can I read REST or SOAP messages into my Streaming EventFlow application?

Use the HTTP Client Input Adapter for any use-case where data is to read from an external web service using the HTTP or HTTPS protocol. 

HTTP is any brief connection to a web service where the adapter is to wait for a response before closing the connection after a timeout and a single response is expected (may be delivered in chunks). REST calls are typically to an end-point that returns a specific response structured as JSON text. SOAP requests are calls to a common end-point where the SOAP request identifies the specific call in an XML structured text message and the response is also an XML structured text message. In all these cases, the underlying protocol is HTTP. For persistent connections where the web server is to deliver periodic messages after an initial connection, use the WebSocket Client Read Adapter instead.

Configure for HTTPS

To support HTTPS (https://) connections protected by SSL/TLS encryption, by default the HTTP Client adapter uses the JVM 'cacerts' file, found in the Java install, for example at:
  C:\tibco\str\11.0\jdk\lib\security\cacerts 

The default certificates are the same that a modern web browser trusts. If you need to trust a specific service's certificate which is not signed by one of the usual public Certificate Authority (CA) providers, then you may use your own truststore with any certificate you have imported into it using StreamBaseEngine .conf setting:

StreamBaseEngine = {
    jvmArgs = [
      "-Djavax.net.ssl.trustStore=C:/keys/truststore.jks"
      "-Djavax.net.ssl.trustStorePassword=secret"
    ]

This selects your truststore (a Java keystore) and overrides use of 'cacerts' for this application. Import a certificate into a truststore using  the 'keytool' command (from a StreamBase Command Prompt), example:
  keytool -import -alias hostname -file certfile.cer -keystore truststore.jks
You will be prompted for the truststore password, which will also replace the word "secret" in the above configuration. If the truststore.jks file does not already exist, then this command will make a new one in the current directory and prompt for a new password. We recommend you do not have spaces, quotes, or other characters with special meaning in your password as this complicates the above configuration. After a truststore file is created it may be moved anywhere on the file system or to another system wherever it may be needed.

EXAMPLE 1 -- REST Request

One use-case is to obtain a secret value from the Azure Key Vault REST API. The REST calls are documented here:
* https://learn.microsoft.com/en-us/rest/api/keyvault/
* https://learn.microsoft.com/en-us/rest/api/keyvault/secrets/get-secret/get-secret?tabs=HTTP
This operation requires the VM user account to have the secrets/get permission.

Configure the HTTP Client for the REST call to the Key Vault API (URL template):
  HTTP GET {vaultBaseUrl}/secrets/{secret-name}/{secret-version}?api-version=7.3
As is expected with REST, the URL provides the entire definition of what is needed without requiring additional data.

In the HTTP Client Adapter StreamBase Properties view, set:

Adapter Properties tab

•   URL:  https://myvault.vault.azure.net//secrets/mysecretname/4387e9f3d6e14c459867679a90fd0f79?api-version=7.3
•   Request Method: GET 
•   Request Type: Basic
•   Download Path: (empty)
•   Asynchronous: (checked)
•   Log Level: INFO

Proxy tab

•   Use Proxy: (unset)

Advanced tab 

•   Connect Timeout: 30000
•   Read Timeout: 30000
•   Reconenct Timeout: 3000
•   Poll Frequency: 0
•   Ignore Certificate Errors: (unchecked)
•   Executor Threads: 3

Output tab

•   Output Input Tuple: (checked)
•   Output Headers: (checked)
•   Output Cookies: (checked)
•   Output Tuple per Line: (unchecked)
  •     Output Blank Lines: (checked)
  •     Output Null Tuple on Completion: (checked)
  •     Output Connecting Status: (checked)
•   URL Decode Data: (unchecked)
•   URL Decode Data Type: QUERY_PARAM_SPACE_ENCODED
•   Use Default Charset: (checked)
  •     Character Set: (disabled)

Auth tab

•   Auth Type: None
•   Username: (empty)
•   Password: (empty)

Cluster Aware tab

•   Cluster start policy: Start with module
•   Deactivate on quorum lost: (unchecked)

Concurrency tab

•   Run this component in a parallel region: (unchecked)
•   Multiplicity: single

This returns a JSON string like this (example):

{
  "value": "mysecretvalue",
  "id": "https://myvault.vault.azure.net/secrets/mysecretname/4387e9f3d6e14c459867679a90fd0f79",
  "attributes": {
    "enabled": true,
    "created": 1493938410,
    "updated": 1493938410,
    "recoveryLevel": "Recoverable+Purgeable"
  }
}

EXAMPLE 2 -- SOAP Request

Another example is to make a SOAP request by identifying the method using a text payload (XML) as an HTTP POST message.

In the HTTP Client Adapter StreamBase Properties view, set:

Adapter Properties tab

•   URL: (empty)
•   Request Method: POST 
•   Request Type: Chunked Response (because SOAP responses may be large)
•   Download Path: (empty)
•   Asynchronous: (checked)
•   Log Level: INFO

Proxy tab

•   Use Proxy: (unset)

Advanced tab 

•   Connect Timeout: 30000
•   Read Timeout: 30000
•   Reconenct Timeout: 3000
•   Poll Frequency: 0
•   Ignore Certificate Errors: (unchecked)
•   Executor Threads: 3

Output tab

•   Output Input Tuple: (unchecked)
•   Output Headers: (checked)
•   Output Cookies: (checked)
•   Output Tuple per Line: (unchecked)
  •     Output Blank Lines: (unchecked)
  •     Output Null Tuple on Completion: (checked)
  •     Output Connecting Status: (unchecked)
•   URL Decode Data: (unchecked)
•   URL Decode Data Type: QUERY_PARAM_SPACE_ENCODED
•   Use Default Charset: (checked)
  •     Character Set: (disabled)

Auth tab

•   Auth Type: None
•   Username: (empty)
•   Password: (empty)

Cluster Aware tab

•   Cluster start policy: Start with module
•   Deactivate on quorum lost: (unchecked)

Concurrency tab

•   Run this component in a parallel region: (unchecked)
•   Multiplicity: single

The input command tuple is constructed in a Map operator as so:

Action,  Field Name, Expression 
Add,     command,    "connect"
Add,     url,        "https://www.dataaccess.com/webservicesserver/NumberConversion.wso"
Declare, txt, 
                '<?xml version="1.0" encoding="utf-8"?>
                <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
                  <soap:Body>
                    <NumberToWords xmlns="http://www.dataaccess.com/webservicesserver/">
                      <ubiNum>499</ubiNum>
                    </NumberToWords>
                  </soap:Body>
                </soap:Envelope>'
Add,     data,       list(tuple( txt as text, false as urlEncode, 'text/xml;charset=UTF-8' as mediaType ))
Add,     settings.requestMethod, 'POST'
Add,     settings.requestType,   "Basic"

In the above example, the SOAP method being called is "NumberToWords" from the "webservicesserver/NumberConversion.wso" endpoint of the "www.dataaccess.com" service.

This results in SOAP response:

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <m:NumberToWordsResponse xmlns:m="http://www.dataaccess.com/webservicesserver/">
      <m:NumberToWordsResult>four hundred and ninety nine </m:NumberToWordsResult>
    </m:NumberToWordsResponse>
  </soap:Body>
</soap:Envelope>

 

Configuration guidance