The Hypertext Transfer Protocol (HTTP) is a request/response network protocol that enables clients and servers to communicate. A client typically submits HTTP requests to a server that hosts a service; for example, a server that provides a resource such as an API with a publicly exposed HTTP endpoint, a website with static content, or a web application with dynamic content and an associated database. On receipt, the HTTP server processes the request and returns a response.

You can use App Connect to pass key data from an app into an HTTP “invoke” action that calls out to an HTTP endpoint, and then pass data returned from the HTTP response into other apps – automatically, in real time. You can do so using configuration and data mapping techniques (without any need for coding), and can achieve a return on your investment in minutes or hours, rather than days or months.

This guide shows you how.

If you can’t find what you want, or have comments about the “how to” information, please either add comments to the bottom of this page or .

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 should I consider first?

Before you use App Connect Designer with an HTTP invoke method, take note of the following considerations:

  • 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 natively installed IBM Secure Gateway Client to set up the required network connection for making a call to the protected endpoint.

    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 App Connect Designer. Also ensure that the HTTP server’s host and port are defined in the Secure Gateway Client’s access control list.

  • To create an integration flow that passes key data between an HTTP server and other apps, you must connect App Connect to each app in the flow. The values required to connect App Connect to your HTTP server are dependent on the type of security scheme configured for the endpoint, and whether the endpoint is publicly available or private. You can add an account for connecting to the HTTP endpoint either from the Applications tab on the App Connect Catalog page, or when you add an HTTP node to a flow.

    Connect to an un-authenticated public endpoint
    If the endpoint is publicly available and requires no authentication, you do not need to specify any connection details. When you click the Connect button for HTTP from the Applications tab on the Catalog page or after selecting the Invoke method action from a flow, you can leave the connection fields blank and simply click Connect again. (You’ll use the Invoke method fields in the flow editor to specify the URL and other configuration options for calling the HTTP endpoint.)
    Connect to a secure endpoint
    If the endpoint is secured using basic authentication, or is on a private network, specify the following connection details:

    • To connect to the HTTP endpoint using basic authentication, complete both of these fields:
      • User name: The name of a user that is authorized to perform HTTP operations.
      • Password: The password for the specified user.
    • If you want to use the Secure Gateway Client to access an HTTP endpoint in a private network, complete both of these fields:
      • Override the HTTP endpoint host name and port of the URL used in the flow: The protocol, host name or IP address, and the port number of the HTTP server in the format http://host:port or https://host:port.
        • How it works

          This protocol, host, and port are used to define a destination for the endpoint, within the Secure Gateway service on IBM Cloud. A corresponding cloud host and port, which are required in order to connect to the protected endpoint, are also generated for the destination. When you create and run a flow, the value specified within the URL (fully qualified) field in the HTTP node will be updated with the cloud host and port that were generated for the destination. This enables the HTTP request to be routed through the Secure Gateway, to the endpoint defined in the override URL.

      • Network name: The name of the network that was configured using the IBM Secure Gateway Client.

        Important: Before you connect the account, ensure that the Secure Gateway Client has been started. If you need to, you can start the Secure Gateway Client as described in Configuring a private network for App Connect Designer: Finally, start and configure the Secure Gateway Client.

    • Example of completed fields for connecting using basic authentication

      Example of HTTP connection details

    • Example of completed fields for connecting to a private network

      Example of HTTP connection details

    Connect to an endpoint by using an override URL
    If you want to specify a URL value that can be used to override the protocol, host, and port in the HTTP endpoint URL being called, complete the Override the HTTP endpoint host name and port of the URL used in the flow field (and leave the Network name field blank). The override URL can be specified in either of these formats: http://host:port or https://host:port. This setting enables you to use the same flow to call different endpoints by setting up multiple accounts with different override URLs.

    • How it works

      At run time, the protocol, host, and port segment of the URL specified within the URL (fully qualified) field in the HTTP node is overwritten with the override URL. For example, if the override URL for account 1 is https://testAPIhost:testPort and the URL (fully qualified) value in the HTTP node is https://APIhost:optionalPort/path?query, at run time, the URL (fully qualified) value is replaced with https://testAPIhost:testPort/path?query. Similarly, running the same (exported) flow using another account with an override URL of https://productionAPIhost:productionPort will convert the URL (fully qualified) value to https://productionAPIhost:productionPort/path?query.

      Override URL example

    Tip: Immediately after you connect, rename your account with a meaningful name that helps you identify which HTTP endpoint and credentials the account relates to. You’ll find this useful if you’d like to set up multiple accounts that enable access to multiple endpoints with varying security credentials. You can rename an account only from the Applications tab on the Catalog page, and before it’s used in a flow. For information about renaming accounts and setting up multiple accounts, see Managing accounts in App Connect.

  • If an HTTP endpoint requires some form of client identifier whenever a request is made (for example, to enable access and calculate usage of an API), you might need to separately configure access to the endpoint as required for the web server, and might also need to specify an API key in the URL that you call from your flow. For example, if you are calling an API, you might need to first enable the API and generate an API key that App Connect can use in the call request. When you call the API from App Connect, you can specify its URL and append the API key as a query parameter. For example:
    https://api.example.url/v1/abc?key=API_key
  • When invoking an HTTP method:
    • The supported HTTP methods are: GET, POST, PUT, PATCH, DELETE, and HEAD.
    • The HTTP and HTTPS transports are supported, and the specified URL must be fully qualified.

      Examples:
      http://www.example.com/
      https://host_name:port/path
      https://my_API_URL?key=API_key&query_parameter1=value1&query_parameter2=value2

      If required, you can also include mapped fields (from previous nodes in the flow) within the URL value that you specify. The following URL example includes a Postal/Zip Code mapped field that was inserted from the list of available inputs (generally accessible by clicking Insert a reference Insert a reference icon):

      HTTP URL field showing a combination of text and mapped fields

      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. For example:
      • Request headers specified as data properties:

        To specify request headers as data properties, you’ll first need to define each property with a data type of String by clicking Add property. Then, click Edit mappings to expose these properties as fields and to 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.

      • Request headers specified as JSON:
        
        {"Accept": "application/json", "Content-Type": "application/json"}
        

        To specify request headers as JSON, click Edit mappings and then specify the JSON.

        Request headers field with JSON specified

        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 Edit mappings 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. For more information about using the App Connect parsers which are available in the toolbox, see:

Troubleshooting tips

If you observe network errors for an HTTP invoke 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:

    Selecting the HTTP status code response

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

Example

Event-driven flow with a JSON Parser node

Create an event-driven flow that parses the response from an HTTP endpoint

Learn how to use App Connect Designer to create an event-driven flow that parses the response from an HTTP endpoint so that some of the data can be inserted into an email to recipients.

Join The Discussion

Your email address will not be published. Required fields are marked *