How to use IBM App Connect with HTTP

A business scenario

The challenge

Let's say your company plans to host a week-long outdoor event, with anticipated attendance figures that run into the thousands. You've set up the event in your ticketing app so potential attendees can book tickets. When each attendee registers, you'd like to send them an email with additional details about the event. And because the event is outdoors, it would be a nice touch to help the attendees 'dress for the weather' by including a weather forecast for each day booked. But, you've got a lot going on and you're hoping there's a quick-and-easy way to ensure each attendee receives the relevant forecast.

How App Connect can help

Use App Connect to set up a flow that queries the Weather API, and then uses the response to add details about the weather forecast to generated emails whenever an attendee registers for your event. By automating this process, you'll free up time to spend doing what really matters – organizing a top-notch event that your attendees will be raving about for years!

What to consider first

Before you use App Connect with an HTTP invoke method, take note of the following considerations that are applicable for a cloud-managed HTTP connector that is hosted in App Connect on IBM Cloud:

• If the HTTP server is in a private network (for example, behind a firewall in an on-premises location or in a private cloud), you'll need to set up a gateway that App Connect will use to securely access the HTTP server. You can use a locally installed IBM Secure Gateway Client to set up the required network connection for making a call to the protected endpoint.
  • How it works
    The Secure Gateway Client in the private network pairs with a Secure Gateway service that is provisioned on IBM Cloud®, to expose the HTTP endpoint outside the private network.

    

    More information:
    Secure Gateway Service
    Getting started with Secure Gateway
• If you've previously used the Secure Gateway Client to set up a network connection for an App Connect application that is on the same private network as the HTTP server, you can use this network connection to access the HTTP endpoint. If you don't have such a network connection in place, configure one as described in Configuring a private network for IBM App Connect on IBM Cloud. Also ensure that the HTTP server's host and port are defined in the Secure Gateway Client's access control list.

Connecting to HTTP

For the considerations and steps you need to connect App Connect on IBM Cloud to an HTTP endpoint, see Connecting to HTTP from App Connect on IBM Cloud and App Connect Enterprise as a Service.

General considerations for using HTTP in App Connect

• (General consideration) You can see lists of the trigger events and actions that are available on the Catalog page of the App Connect Designer.

  For some applications, the events and actions in the catalog depend on the environment (IBM Cloud Pak for Integration or App Connect on IBM Cloud) and whether the connector supports configurable events and dynamic discovery of actions. If the application supports configurable events, you see a Show more configurable events link under the events list. If the application supports dynamic discovery of actions, you see a Show more link under the actions list.

• (General consideration) If you are using multiple accounts for an application, the set of fields that is displayed when you select an action for that application can vary for different accounts. In the flow editor, some applications always provide a curated set of static fields for an action. Other applications use dynamic discovery to retrieve the set of fields that are configured on the instance that you are connected to. For example, if you have two accounts for two instances of an application, the first account might use settings that are ready for immediate use. However, the second account might be configured with extra custom fields.
• For the Invoke method action:
  • The supported HTTP methods are: GET, POST, PUT, PATCH, DELETE, and HEAD.
  • The HTTP and HTTPS transports are supported, and the URL that you specify must be fully qualified. Examples:

    http://www.example.com/

    https://host_name:port/path

    https://my_API_URL?query_parameter1=value1&query_parameter2=value2

    The URL can also contain mappings from previous nodes in the flow. The following example shows a Postal/Zip Code mapping that was inserted using Insert a reference:

    

    Note: If you specified an override URL when connecting to the HTTP account, the protocol, host name, and port that you specify in the URL (fully qualified) field will be replaced with your override settings when the flow runs.
  • Request headers (if required to define additional operating parameters) can be specified as data properties (with a name and String data type) or as a JSON object that consists of comma-separated name/value pairs.
    • To specify request headers as data properties:
      1. Click Add property to define each property with a data type of String.

         

      2. Click Edit mappings to expose these properties as fields and then specify their values. (To add or remove properties, you can click Edit properties.)

         

         To update the name of a defined property, you must ensure that the associated field is empty before you click Edit properties. For more information about specifying data properties, see Defining your own data properties.

    • To specify request headers as JSON (for example {"Accept": "application/json", "Content-Type":"application/json"}), click Map to object and then enter the JSON.

      

      If you've already defined one or more property fields under the Request headers heading, but would prefer to use JSON instead, you must delete those properties and then click Map to object to display a Request headers field that you can type into.

  • Optionally implement your own error handling within the flow by indicating whether the flow should continue if something unexpected occurs. Set Continue flow (non-2xx) to true to continue running the flow if a status code other than 2xx (Success) is returned by the HTTP call.

    

    If set to false (the default), flow processing stops when a non-2xx status code is issued.

  • A maximum of three attempts are made to call the HTTP server, with a five-second delay between retries. A flow will typically time out after 60 seconds.

Ways of processing the HTTP response

The response from an HTTP invoke method is returned in a format supported by the endpoint – for example, JavaScript Object Notation (JSON), XML, or CSV format – and is passed as a string. To map the response headers and response body in a subsequent action in your flow, you'll need to use one of the built-in parsers in App Connect to convert the string into an object that represents the string. For example, if the response is in JSON format, you can use the JSON parser to convert the JSON string into a JSON object. You can map to the response by selecting either Response headers or Response body (as appropriate) under HTTP / Invoke method in the list of available inputs.

For more information about using the App Connect parsers which are available in the toolbox, see:

• Using the JSON parser to parse a JSON string into a JSON object
• Using the CSV parser to parse CSV text into a JSON object
• Using the XML parser to parse an XML string into an XML object

Troubleshooting tips

If you observe network errors for an HTTP Invoke method action in your flow, the cause might be related to connectivity or security issues. Use these tips to help with error resolution:

• Verify that the network is available and that the HTTP server can be reached. For example, the error might be due to a network timeout.
• If your HTTP account is configured to make requests through a Secure Gateway Client, ensure that the Secure Gateway Client is correctly configured to allow access to the HTTP endpoint's host and port, and that it is running. For more information, see Configuring a private network for IBM App Connect on IBM Cloud.
• If you can successfully call out to the HTTP endpoint using a utility such as Postman, verify that your request header specifications in that utility are identical to those specified in the Request headers field of your HTTP node.
• Investigate whether the issue is caused by SSL certificate errors. App Connect uses Transport Layer Security (TLS) to establish a secure communication channel to the HTTP endpoint, and will reject the certificate that a target server presents if issues are detected; for example, if it's untrusted or expired, or has missing intermediate (or chain) certificates.

  If you can successfully call out to the HTTP endpoint using an external utility, check whether SSL certificate checking is enabled for that utility. If it isn't, you can enable it and test the call again to see whether it passes.

• To help you determine the cause of the error, ensure that the Continue flow (non-2xx) field is set to true and then map to the HTTP response status code in a subsequent node in the flow. For example:

  

  Then run the flow again and check to see which status code is returned.

Events and actions

HTTP events

These events are for changes in this application that trigger a flow to start performing the actions in the flow.

HTTP actions

These are actions on this application that you want a flow to complete.

Request

Invoke method