Call a REST API using the HTTP v2 connector in Jitterbit Studio

Introduction

The HTTP v2 connector establishes access over the HTTP or HTTPS protocol to services such as REST APIs, GraphQL APIs, and web forms.

This guide covers two common patterns for working with REST APIs in Studio:

• Using an HTTP v2 GET activity as a source to retrieve data from a REST API endpoint.
• Using an HTTP v2 POST activity as a target to send data to a REST API endpoint, including webhooks.

The same principles apply to the PUT, PATCH, and DELETE activity types.

Configure an HTTP v2 connection

Before creating HTTP v2 activities, configure a connection to the REST API.

1. In Studio, open a project and click the Project endpoints and connectors tab in the design component palette.

2. Click the HTTP v2 connector to open the connection configuration screen.

3. Connection Name: Enter a unique name that identifies the REST API service, for example Customer API. The name must not contain forward slashes / or colons :.

4. Base URL: Enter the API's base URL, for example https://api.example.com/v1. Individual activities can extend this URL with a path suffix or override it entirely with a full URL.

5. Authorization: Use the menu to select the authentication type required by the API. Common choices include:

   • No Auth: For public endpoints that require no authentication.
   • API Key: Sends a key-value pair as a header or query parameter.
   • Bearer Token: Sends a bearer token in the Authorization header.
   • Basic Auth: Sends a base64-encoded username and password in the Authorization header.

   For a full description of all authentication types, see HTTP v2 connection authentication types.

   Tip

   Connection fields support project variables. Use project variables for credentials such as API keys, bearer tokens, and passwords to avoid storing sensitive values directly in the connection configuration.

6. Click Test to verify the connection. A test is successful if the API returns any 2xx status code (or 405 Method Not Allowed).

7. Click Save Changes.

Retrieve data using a GET request

An HTTP v2 GET activity is used as a source in an operation. It sends an HTTP GET request to the REST API and provides the response as input to the next step in the operation, typically a transformation.

The operation follows the transformation pattern:

Create a GET activity

On the design component palette, expand the HTTP v2 endpoint you created. Drag the GET activity type onto the design canvas to create an activity instance. Double-click the activity to open its configuration.

Step 1: Enter a name and specify settings

1. Name: Enter a unique name for the activity, for example Get Customer.

2. Path: Enter the resource path relative to the Base URL, for example /customers/{id}. The complete runtime URL is shown in the URL field below Path.

   • If left blank, the Base URL from the connection is used at runtime.
   • A partial path is appended to the Base URL.
   • A full URL overrides the Base URL.

   To include a path parameter, enclose it in curly brackets, for example {id}. For more information, see Use variables in the URL path below.

3. Request Parameters: Click the add icon to add query parameters as key-value rows, for example limit / 100. Request parameters are automatically URL-encoded.

4. Request Headers: Click the add icon to add request headers as key-value rows, for example Accept / application/json. Headers defined here are applied in addition to any headers defined on the connection.

5. Click Next.

Steps 2 and 3: Provide schemas

Step 2 lets you provide a custom request schema (optional for GET requests, which typically have no body). Step 3 lets you provide a custom response schema.

If the REST API returns a known JSON structure, provide a custom JSON schema in Step 3 by selecting Yes, Provide New Schema and entering or pasting the schema. This allows the transformation to map individual fields from the API response.

If no custom response schema is provided, the connector's default response schema is used. The default schema exposes the full response body as a single responseContent field.

Step 4: Review the data schemas

The configured request and response schemas are displayed. Click Finished to save the activity configuration. The schemas are also available in any adjacent transformation on the design canvas.

Access the response in a transformation

In the downstream transformation, map fields from the GET activity's response schema to the target schema:

• If a custom response schema was provided, the individual fields from the parsed JSON response are available for mapping.
• If the default response schema is used, the responseContent field contains the raw response body as a string. Use the JSONParser function in a script to parse it if needed.

Send data using a POST request

An HTTP v2 POST activity is used as a target in an operation. A transformation maps source data into the POST request body, and the activity sends it to the REST API endpoint. This pattern also applies to sending data to webhook endpoints.

The operation follows the transformation pattern:

Create a POST activity

On the design component palette, drag the POST activity type from the HTTP v2 endpoint onto the design canvas. Double-click the activity to open its configuration.

Step 1: Enter a name and specify settings

1. Name: Enter a unique name for the activity, for example Create Order.

2. Path: Enter the resource path relative to the Base URL, for example /orders. To send to a webhook, enter the full webhook URL here: a full URL overrides the Base URL from the connection.

3. Request Headers: Add any headers required by the API. For REST APIs that accept JSON, add Content-Type / application/json.

4. Click Next.

Steps 2 and 3: Provide schemas

Step 2 (Request schema) defines the structure of the request body. Step 3 (Response schema) is optional and captures the API's response.

To define the request body structure:

1. In Step 2, select Yes, Provide New Schema and enter or paste the JSON schema that matches the API's expected request body. The fields in this schema become available in the upstream transformation for mapping.

2. In Step 3, optionally provide a response schema to capture fields returned by the API, for example a created resource ID.

3. Click Finished.

Map source data to the request body

In the upstream transformation, map source fields to the fields defined in the POST activity's request schema. The transformation output becomes the HTTP request body at runtime.

Use variables in the URL path

URL paths can be made dynamic using three techniques:

• Path parameters are placeholders in the Path field enclosed in curly brackets, for example /customers/{customerId}. At runtime, the connector substitutes the value of the matching field from the request schema. In the upstream transformation, map the source value to the customerId field in the request schema.

• Project variables can be used anywhere a variable icon appears in the connection or activity fields. Type an open square bracket [ into the field or click the variable icon to select a project variable. This is useful for environment-specific values such as a base URL that differs between development and production. See project variables for more information.

• Global variables can be set by a script that runs before the HTTP v2 operation in an operation chain. The script assigns a value to a global variable (for example, $gv_customer_id = "12345"), and the Path field references the variable (for example, /customers/$gv_customer_id). See global variables for more information.