The concept of an HTTP (Web) service is an open standard (JSON, XML, SOAP, HTTP, etc.) based web application that communicates with other web applications for the purpose of exchanging data.

In practice, using a protocol such as HTTP to transfer data in machine-readable file formats such as XML and JSON is a standardized way of providing interoperability between disparate applications.

The primary use case for Asynchronous HTTP is to poll the server for a delayed response. Asynchronous HTTP still requires a response, but the response can be processed in another thread of execution or later in an event loop.

In Synatic, the Destination HTTP Async Service Step provides this function and generally allows the flow to send or write data to a web-based API.

Using an HTTP Async Service Step

The HTTP Async Service step is located in the Source drawer in the Steps palette. To use the HTTP Async Service step:

Select and drag the HTTP Async Service step to the desired location in the flow.
Give the step a name and a short meaningful description.

Note: To add the Destination HTTP Async Service step:

Insert the HTTP Async Service step directly after a few processing steps in the flow, for example, JSON, and then followed by a Mapper and an XML writer step.
The request is then submitted to the Destination Async HTTP Service.

Configuring the HTTP Async Service step

The configuration for this step involves several options and settings.

URL

Enter the URL of the HTTP Service.

HTTP Method

The common HTTP method to use is POST.
Learn more about HTTP Methods.

Authentication Method

Click the + icon to select and configure the HTTP Authentication type:

Auth Type - None - No authentication is required and therefore is not applied.
Auth Type - Basic - Requires a standard username and password. In basic HTTP authentication, a request contains a header field in the form of Authorization: Basic <credentials>
Auth Type - OAuth2 is the industry protocol for distributed authorization. Generally, OAuth provides clients a secure delegated access to server resources on behalf of a resource owner.
- See more detail in the Example below.
Auth Type - Header

Options

Headers

Click the + icon to add any Headers you want to submit to the HTTP Service.
Enter the headers you want to submit.

Async

Parallel Calls: Enter the number of requests to submit concurrently.
Check Location: Depending on the API, enter the location, where the asynchronous result is located, into one of the following fields:
- Path: Enter the location using the {@path} syntax.
- Header: Enter the Header value containing the path.
- Body Path: Enter the value in the body containing the path.
Polling: Set the frequency of the location checks.
- Interval: Enter the polling interval in seconds.
- Maximum: Enter the maximum number of calls before timing out.

Checks: The option settings below define when the asynchronous request has completed or has raised an error.

Completion Check: The settings below define when the asynchronous request has completed.
- Path: Enter the path of the value containing the result.
- Operation: Select the relevant equality operator where:
• = is equivalent to x is equal to y.
• != is equivalent to x is not equal to y.
• Has is equivalent to contains the value x.
- Value: Enter the code to define test criteria for the returned value.

Error Check: The settings below define when the asynchronous request returns an error.
- Path: Enter the path of the value containing the result.
- Operation: Select the relevant equality operator where:
• = is equivalent to x is equal to y.
• != is equivalent to x is not equal to y.
• Has is equivalent to contains the value x.
- Value: Enter the code to define test criteria for the returned value.

Advanced Mode Options

Click on the Advanced Mode text button to display the following advanced options:

Disable Streaming: Select the checkbox to disable HTTP streaming and buffer results to send requests as one POST.
Record IO: Capture and save the IO value sent.

Examples

When selecting an Auth Type of oAuth2 in a typical web request to an API, the following type of configuration may apply:

Configure the following fields with the correct values to process successful web requests:

Note: The options marked with an * are required fields.

OAuth Provider URL* - The oAuth2 provider URL to call for authentication.
OAuth Token URL* - The oAuth2 provider URL to generate tokens from.
Client ID* - The client id issued by the provider.
Client Secret* - The client secret issued by the provider.
Response Type* - Select the Response type the request will respond with as either a Code or a Token.
Grant Type* - Select the oAuth2 Grant type to use: Authorization Code.
Use Refresh as Token - Select this option if your provider does not support refresh tokens but uses long-lived tokens.
One use Refresh Token - Select this option if your provider does not support using a refresh token more than once.
No Query String - Select this option if you don't want to send parameters in the query string.
Scopes - A Scope is a mechanism in OAuth 2.0 that limits an application's access to a user's account. An application can request one or more scopes, and the access token issued to the application will be limited to the scopes granted.
Additional QS Values - You can also add additional Query Strings (QS) to the HTTP Service request by adding parameters here.
Note: These parameters will not be submitted if you select the No Query String checkbox.

When selecting an Auth Type of Basic in a typical web request to an API, the following type of configuration may apply:

 auth=HTTPBasicAuth('user', 'pass'))

Enter your credentials as a standard username and password.

Limitations and known issues

None.

Useful Tutorials

Revisit the Getting Started page for a refresher.