Skip to main content
Feedback

Configuring a POST request

Blueprints in Data Integration let you define and reuse API integrations using YAML. This topic explains how to configure a POST request step in your connector. You use POST requests to send data to an API to create or update a resource.

  1. Log in to the Data Integration console.
  2. From the left-hand menu, click Blueprints.

The list of available Blueprints along with their ID, modified by, and last modified details appears. You can create a new one by adding a Blueprint.

Adding a Blueprint

  1. Click the Add Blueprint in the top-right corner.
  2. Enter a Blueprint name.
  3. In the YAML Template dropdown, select one of the following:
    • Basic – A single-step template for simple API requests.
    • Single Loop – A template for API that use pagination.
    • Double Loop – A template for API that require nested loops (for example, accounts and their related transactions).
  4. Alternatively, click Use our YAML Builder to start writing YAML from scratch.

Defining interface parameters

Interface parameters are reusable values that you can insert into endpoints or request bodies.

Example

interface_parameters:
  section:
    source:
      - name: var
        type: string
        value: "from"

Explanation name: The parameter name. type: Parameter data type. value: The default value used when the Blueprint runs.

In this example, var is a string parameter with the value from. You can reference it inside the request body.

Configuring the connector

You must configure the connector block to define the API host, authentication, and storage settings.

Example

connector:
  name: HttpBin API
  type: rest
  base_url: "https://httpbun.com"
  default_headers:
    "Content-Type": "application/json"
  variables_metadata:
    final_output_file:
      format: json
      storage_name: results_dir
  variables_storages:
    - name: results_dir
      type: file_system

Explanation

  • name: A descriptive name for the connector.

  • type: The connector type, here rest.

  • base_url: Specifies the API host.

  • default_headers: Defines request headers such as Content-Type. Most common options include:

    • application/json: Most common for modern API.
    • application/x-www-form-urlencoded: Used by traditional web forms.

  • variables_metadata: Declares how output is stored, including format and storage name.

  • variables_storages: Configures where the system saves the response (for example, file system).

Adding a POST request step

You can add workflow steps inside a Blueprint. By default, a new Blueprint includes one REST step. You can configure it to use POST.

Example

steps:
  - name: PostToAnything
    description: "Send POST request to /any endpoint on httpbun.com"
    type: rest
    http_method: POST
    expected_status_codes: [200]
    endpoint: "{{%BASE_URL%}}/any"
    body: '{"message":"Hello {var} Rivery Connector Executor"}'
    variables_output:
      - response_location: data
        variable_name: final_output_file
        variable_format: json
        transformation_layers:
          - type: extract_json
            from_type: json
            json_path: $.json

Explanation

  • name: The step name.
  • description: A short description of what the step does.
  • type: The step type, here rest.
  • http_method: Sets the request type to POST.
  • expected_status_codes: Defines the expected successful response codes.
  • endpoint: Appends to the base URL.
  • body: Defines the request payload. Here, it includes a variable.
  • variables_output: Extracts values from the response and stores them.

Creating the request body

The request body defines the data you send in the POST request.

If you select application/json as the content type, you must provide a valid JSON object in the Request Body field.

You can also use variables from previous steps or interface parameters. Wrap variables in {{%...%}}.

Example

{
  "name": "{{%user_name%}}",
  "email": "{{%user_email%}}",
  "plan": "premium",
  "metadata": {
    "source": "builder"
  }
}

Explanation

  • name, email, plan: Values required by the API.
  • metadata: An optional nested object.
  • {{%user_name%}}**, **{{%user_email%}}: The system replaces these variables at runtime.

Optional: Configuring advanced settings

You can also configure advanced POST request options:

  • Retry Strategy: Define retry count and intervals for specific HTTP status codes.
  • Pagination: Configure if the API supports pagination for POST requests.
  • Variable Outputs: Extract and store data from the response for later steps. For example, Capture the ID of a newly created resource.

Example

- name: Create New User
  description: Creates a new user in the system
  type: rest
  http_method: POST
  endpoint: "{{%BASE_URL%}}/users"
  headers:
    Content-Type: application/json
  body:
    name: "{{%user_name%}}"
    email: "{{%user_email%}}"
    plan: "premium"
  variables_output:
    - response_location: data
      variable_name: new_user_id
      variable_format: json
      transformation_layers:
        - type: extract_json
          from_type: json
          json_path: "$.id"

Handling Errors in loop components

When using loops within a Blueprint such as Single Loop or Double Loop templates, you can control how the system behaves if an iteration fails.

You can add the following new fields inside the loop block:

steps:
  - name: LoopOverCurrencyPairs
    description: "Loop over each pair to get conversion per amount"
    type: loop
    loop:
      type: data
      variable_name: "{ext.currencies}"
      item_name: "currency"
      add_to_results: true
      ignore_errors: true           # continue iterations on API error
      expected_status_codes: [200]  # stop the run if response is not 200

ignore_errors: true — allows the loop to continue running even when some API calls fail. expected_status_codes: [200] — stops execution if an API response does not match the expected success code.

If both options are used together, the system raises a warning indicating that expected_status_codes takes precedence and the loop will still fail on non-matching responses.

Testing the blueprint

  1. In the right-hand panel, click Test Blueprint.
  2. Verify that the system sends the POST request to https://httpbun.com/any.
  3. Confirm that the system captures and saves the response JSON to the results_dir storage as final_output_file.
On this Page