HTTP

HTTP Steps can be used to interact with REST-based APIs as part of your business process. At minimum, HTTP Steps require their input to include the method type and the URL. If a response is returned from the API, it is stored in the Step Context's output.response field.

By convention, REST APIs use different request methods for different purposes. For example, to retrieve information you would typically use a GET method. Similarly, for creating new resources, you'd use a POST method. Please refer to your API documentation to learn about your specific requirements.

For more information about HTTP and REST requests, please see http.dev.

Video Overview

Input

Field	Description	Mandatory	JSON Example
method	One of GET, POST, PUT, DELETE, PATCH, OPTIONS, or HEAD.	✔	"GET"
url	The full url to use when sending the GET request, including the port.	✔	"https://your-host.com:8000/api/getUsers"
headers	A list of key/value pairs to represent headers.		{ "Content-Type": "application/json" }
body	The body of the HTTP request, applicable for methods like POST, PUT, and PATCH.		{ "data": "sample data" }
params	A list of key/value pairs for query parameters.		{ "userId": 123, "userName": "Jon Snow" }
includeFullResponseString	If true, stores the Get response body in output.fullResponseString. Defaults to false.		true
responseSelectors	See description below.		{ }
repeatUntilEnabled	Enables the repeat-until mechanism, allowing the step to be retried until a certain condition is met.		true
repeatUntilCondition	A script defining the condition to evaluate after each retry. Must return a boolean value.		(steps, context) => {return steps.__self.output.response.counter === 100;}
repeatIntervalSeconds	The interval in seconds between each retry attempt.		10
maxRepeatCount	The maximum number of retry attempts allowed.		5
allowXmlToJsonConversion	If true, automatically converts XML responses to JSON so it's easier to manipulate in future steps. Defaults to true.		true

Body

The body field allows you to define the payload of your HTTP request. It is particularly useful for methods like POST, PUT, and PATCH where you need to send data to the server.

Field	Description	Mandatory	JSON Example
contentType	The MIME type of the request body, e.g., json.	✔	"json"
body	The actual content of the request body.	✔	{ "key": "value" }

Output

Field	Description
statusCode	The HTTP response code, if received.
selectedBody	A key/value object of JSON nodes, as specified by the responseSelector.bodyJsonPaths selector.
selectedHeaders	A key/value object of headers according to the responseSelector.headers selector.
fullResponseString	If input.includeFullResponseString is set to true, stores the raw HTTP response body.
response	The response body, optionally normalized if the response includes a Content-Type header.
transformed	The JSON payload after being processed by the JQ Transformer. See below for details.

Response Selectors

Response Selectors provide a means to extract specific information from the HTTP response and to store it directly in the output. This is particularly useful in cases where the expected payload is known in advance and the required data can be extracted from the headers directly, or from the body using the JsonPath query language.

responseSelector accepts the following optional fields:

Field	Purpose
headers	The set of headers you'd like to copy from the response into output.selectedHeaders.
bodyJsonPaths	A key/value set that maps identifiers to JsonPaths. If the JsonPath returns a result, it is stored in output.selectedBody[identifier].

Please see this link to learn more about JsonPath.

Example ResponseSelector

The example below shows how to use the responseSelector to copy one specific header (X-Tenant-ID) and to compose a custom payload that extracts the version number and the Stark characters names.

Payload Headers

X-Tenant-ID: 505
Content-Type: application/json

Payload Body

{
    "metadata": {
        "version": 5
    },
    "characters": [
        {
            "id": 1,
            "name": "Jon Snow",
            "house": "Stark",
            "title": "King in the North"
        },
        {
            "id": 2,
            "name": "Daenerys Targaryen",
            "house": "Targaryen",
            "title": "Mother of Dragons"
        },
        {
            "id": 4,
            "name": "Arya Stark",
            "house": "Stark",
            "title": "No One"
        }
    ]
}

Response Selector

{
    headers: ["X-Tenant-ID"],
    bodyJsonPaths: {
        version: "$.metadata.version"
        starks: "$.characters[?(@.house == 'Stark')].name"
    }
}

Output

{
    "selectedHeaders": {
        "X-Tenant-ID": 505
    },
    "selectedBody": {
        "version": 5,
        "starks": [ "Jon Snow", "Arya Stark" ]
    }
}

info

Any errors found during the processing of bodyJsonPaths will be recorded in the output.selectedBody.__selectorErrors field.

JQ Transformer

HTTP Steps can additionally define a JQ Transformer to manipulate the response payload and store its result in the output.transformed field of the Step Context. For more information about JQ support in Unmeshed, see JQ Step

Repeat Until Configuration

The repeatUntil mechanism allows the HTTP step to be retried until a specified condition is met. This is useful for scenarios where you need to wait for a certain state or condition to be fulfilled before proceeding.

tip

Poll for condition to match scenarios can be easily managed with this step

Fields

Field	Description	Mandatory	JSON Example
repeatUntilEnabled	Enables the repeat-until mechanism, allowing the step to be retried until a condition is met.		true
repeatUntilCondition	A script defining the condition to evaluate after each retry. Must return a boolean value.		{ "script": "return response.status === 200;" }
repeatIntervalSeconds	The interval in seconds between each retry attempt.		10
maxRepeatCount	The maximum number of retry attempts allowed.		5

How It Works

1. Enable Repeat Until:

   • Set repeatUntilEnabled to true to activate the repeat mechanism.

2. Define Condition:

   • Provide a repeatUntilCondition script that evaluates the response and returns true when the desired condition is met.

3. Set Retry Parameters:

   • repeatIntervalSeconds: Specifies how long to wait between each retry attempt.
   • maxRepeatCount: Limits the number of retries to prevent infinite loops.

Example Repeat Until Configuration

{
    "repeatUntilEnabled": true,
    "repeatUntilCondition": {
        "script": "return response.status === 200;"
    },
    "repeatIntervalSeconds": 10,
    "maxRepeatCount": 5
}