The HTTP Client Function enables communication with a third-party HTTP server. Using it stream editors can control outgoing requests handling. This Function supports REST API and also supports authentication via the OAuth 2.0 framework. The following HTTP Client Functions are available in Usage Engine:

• Collector
• Processor
• Forwarder

The options available under General Settings and Advanced Settings that are applicable to HTTP Client Collectors, Processors, and Forwarders are mentioned below. options are available under the Parameters and Configuration tabs. The Parameters tab allows you to set the values for how the HTTP Client Function would behave when communication with the third-party HTTP server. The Configuration tab allows you to specify the method of communication.

The options specific to each of the individual Functions are mentioned in the corresponding sections:

...

3 Functions, whether it is for Collector, Processor or Forwarder, will be mentioned in their corresponding sections at the end of this page.

Parameters

Under Parameters, you get the Connection and Operational Settings that are applicable to HTTP Client Collectors, Processors, and Forwarders.

Connection

Depending on the users' configuration, two authentication methods are available: Basic authentication and OAuth 2.0 implementation. A selectable option from the Authentication type is used to make the selection and based on that separate configuration options are available. . There will be additional options in the Configuration tab for the Authentication type selected.

Basic Authentication

In General Settings,  enter the following details:

1. Select Add the Username and Password if there are any. These options can be left empty.
2. Add the Target URL of the HTTP request to be made to the HTTP server.

3. In the Configuration tab,  select an HTTP request method from the following options:

   HTTP Method	Description
   GET	Requests data from the target server
   POST	Sends data to the target server. Select either Body or Form under Content*
   PUT	Replaces the current resources of the target URL with the uploaded content. Select either Body or Form under Content*
   PATCH	Updates partial resources of the target URL. Select either Body or Form under Content*
   DELETE	Removes all current representations of the target resource

   
   

   Note
   title URL Entry
   Cloud Edition interprets only a single forward slash in the URL fields. Make sure that you format the URLs accordingly.

   
   

   Note
   title Note!
   *The Body and Form fields are visible only for request methods POST, PUT and PATCH.

   • Select Body or Form and add the corresponding details in the content of the request message. You can use Variable Insertion.
     
   • Expand the examples below to view samples of HTTP request messages for Body or Form:

   Note
   title Note!
   The form input needs to be URL encoded, otherwise, it fails. HTTP requests use a hardcoded content-type value of ‘application/x-www-form-urlencoded’.

   
   

   Expand
   title Sample of an HTTP body content message
   No Format { "name" : "my_username", "first-name" : "My", "last-name" : "Username", "display-name" : "My Username", "email" : "user@example.test", "active" : true }

   
   

   Expand
   title Sample of an HTTP form content message
   No Format name=my_username&first-name=My&last-name=Username&display-name=My%20Username&email=user@example.test&active=true

   
   

4. In Target URL, enter the URL of the target HTTP server.  You can use Variable Insertion.  You can select a combination of the following options to be included in the URL:

   Option	Description
   Include basic access authentication credentials	Select to add the specified username and password
   Include query string in URL	Select to include a query string in the URL. Add a key and its corresponding value. You can include multiple query strings.
   Customize header	Select to customize the headers of the URL and specify multiple keys and their respective values. The default value for the HTTP headers “content-type” and “accept” is application/json. You can override the default value for HTTP header “content-type”. It is recommended that the default value for HTTP header "accept" is left unchanged. The HTTP Functions only support application/json.

   
   

OAuth 2.0 Authorization

The HTTP Method, Target URL, and associated options are configured in the same way. When the Authentication type selection is selected as OAuth 2.0 additional options are displayed. Their configuration is mandatory to properly activate the Function. 

...

The Configure Token section of the Function controls the authentication token credentials. The Header Prefix field is the Authorization header placed before the access token. Based on the Grant Type selection there are two types of credentials access provided for the authentication provisions – Password and Client credentials. Each of them has a distinctive configuration option. 

...

• Include query string in URL – This enables a query string in the token URL. 
• Customize header - This allows for custom headers to be specified.Advanced

Operational Settings

In Advanced Operational Settings, enter the following details that determine how you want to handle the errors. The following options are available for HTTP Collector and Processor Functions only:

...

To configure this Function, take the following steps in addition to the ones mentioned in the General Settings Connection and Advanced Operational Settings:

In Request run limit, specify the number of times the operation should run. 

...

In addition to the steps mentioned in the General Settings and Advanced the Connection and Operational Settings, you can take the following optional steps to configure HTTP Client processor:

...

In addition to the steps mentioned in the General Settings and Advanced Connection and Operational Settings, you can take the following optional steps to configure HTTP Client forwarder:

• In Maximum number of parallel requests, specify the maximum number of parallel requests that can be handled simultaneously.  

• You can toggle on the Retry on fail functionality, allowing the service to retry the operation when an error has occurred. You can specify the number of retries in the Number of retries box, where the retries will be attempted inside the dynamically adjusted period of retry time.
  

  Note
  title Note!
  The maximum number of allowed retries is 12 and all retries will be attempted in a total span of approximately 68 minutes.

  
  

  Info
  title Use Case Scenario
  The Retry on fail functionality can be used when servers respond with error codes such as 500 or 503 due to intermittent server issues. The retry on fail option allows users to retry sending the requests a set number of times. This is only useful for 5xx error codes.

  
  

• You can choose to either Ignore or Stop the stream when an error is detected.