Using the HTTP API

The HTTP API provides functionality to perform various of different HTTP related queries.

Basic usage of the API:

const response = context.httpAPI()
    .newRequestBuilder()
    .get('https://service')
    .build()
    .perform();
if (response.succeeded()) {
    const data = response.bodyText();
}

Example how to use the HTTP API to POST a JSON structure including adding custom request headers.

const theObject = {};
const response = context.httpAPI()
    .newRequestBuilder()
    .url('https://service')
    .method('POST')
    .header('A Header', 'Some Value')
    .authorization('Bearer ABCDEF') // Same as setting the header 'Authorization' to the value
    .acceptsJson() // Same as setting the header 'Accept' to 'application/json'
    .jsonBody(JSON.stringify(theObject))
    .build()
    .perform();
if (response.succeeded()) {
    const data = response.bodyText();
}

Example how to use the HTTP API to POST form parameters.

const response = context.httpAPI()
    .newRequestBuilder()
    .post('https://httpbin.org/post')
    .header('Content-type', 'application/x-www-form-urlencoded')
    .postParams()
        .param('client_id', 'test1')
        .param('client_secret', 'test2')
        .param('scope', 'a b c')
        .and()
    .build()
    .perform();

If you have some common endpoints often called, these could be declared as destinations within the Administration UI. Each destination is given a unique name that you refer to from the code. The benefits to use destinations are:

Less code in the configuration
The definition of the endpoint is declared in one place only.
- Easy to update and adopt to changes
Authorization details can be configured instead of expressed in code
You can override or configure the request further on in the code.
- For example many services uses the same base URL and authentication but there are variations in the URL and/or in the request data passed.

context.httpAPI()
    .newRequestBuilder('the-name-of-your-destination')
    // configure request more..
    .build()
    .perform();

Read more about named destinations here.

Retry Settings

The HTTP API has built-in support for retry handling. The retry settings are configured via the retrySettings() method on the RequestBuilder.

The retry settings that can be controlled are:

Setting	Description	Default value
Max Attempts	Controls the max number of attempts including the initial request	7
Delay	Defines the initial delay to wait until next attempt is made	2 seconds
Backoff Multiplier	A multiplier to be applied on the delay after each retry	2.0
Max Delay	The maximum delay to wait between two attempts	1 minute
Allowed HTTP status codes	The list of HTTP status that are considered as safe to perform a retry for	408, 429, 500, 502, 503, 504
Honor "Retry After" HTTP response header	If the server returns a "Retry After" header, we should honor this. This is often used for 429 responses	True
Allowing non idempotent request methods	Whether to also allow retries for HTTP methods like POST and PATCH. Must be manually configured per request to TRUE to allow retries on such request.	False

Setting

Description

Default value

Max Attempts

Controls the max number of attempts including the initial request

Delay

Defines the initial delay to wait until next attempt is made

2 seconds

Backoff Multiplier

A multiplier to be applied on the delay after each retry

2.0

Max Delay

The maximum delay to wait between two attempts

1 minute

Allowed HTTP status codes

The list of HTTP status that are considered as safe to perform a retry for

408, 429, 500, 502, 503, 504

Honor "Retry After" HTTP response header

If the server returns a "Retry After" header, we should honor this. This is often used for 429 responses

True

Allowing non idempotent request methods

Whether to also allow retries for HTTP methods like POST and PATCH. Must be manually configured per request to TRUE to allow retries on such request.

False

To adjust the retry settings for a specific HTTP call, one do so like below:

const response = context.httpAPI()
    .newRequestBuilder()
    .method('POST')
    .url(url)
    .retrySettings() // *** controls retry settings
        .maxAttempts(15) (1)
        .delayMs(1000) (2)
        .backoffMultiplier(1.5) (3)
        .maxDelayMs(60000) (4)
        .statusCodes(408, 429, 500, 502, 503, 504) (5)
        .allowNonIdempotentRetries(true) (6)
        .honorRetryAfterHeader(true) (7)
        .and() (8)
    .build()
    .perform();

1	Specifies max attempts. Set to 1 to disable retries
2	Configure the delay in milliseconds
3	Configure the back-of multiplier to be applied on the delay after each retry
4	The max delay in milliseconds
5	Specify status codes that are allowed / safe to perform retry on
6	Whether to allow retries on NON idempotent requests (POST, PATCH)
7	If to honor Retry After response header if sent by server
8	Completes the retry settings configuration block

To disable the retry support, do like:

const response = context.httpAPI()
    .newRequestBuilder()
    .method('POST')
    .url(url)
    .retrySettings()
    .disable() (1)
    .build()
    .perform();

1	Calling disable is a short hand for calling `setMaxAttempts(1)` and `and()`.

The total time spent on retrying HTTP calls may not exceed 5 minutes during the execution of a single job.

URL Builder / Path Variables

Using the URL builder to construct URLs:

const response = context.httpAPI()
    .newRequestBuilder()
    .url() // urlbuilder
    .base('https://service/test/${ID}/something/${TYPE}')
    .replacePathVariables({ 'ID' : '1234', 'TYPE' : 'Item'})
    .param('param1', 'value1')
    .and() // complete urlbuilder
    .build()
    .perform();