Multipart request formats

Use multipart request formats to define multipart request bodies and configure form-data parameters for API requests.
Note: The Map input document to API request check box does not influence multipart requests.

Overview

Format

The request can have these request formats:

  • application/x-www-form-urlencoded - Define multipart request body by form-data parameters.
  • multipart/form-data - Define multipart request body by form-data parameters.
Form Data Parameters
If the multipart request body format is selected, the list of form parameters is displayed.

Form-data parameters

This table shows the description of available columns:

Column Description
Name The form-data parameter name as defined in the API metadata. An asterisk indicates whether a value is required for this parameter.
Data Type The parameter data type and optional data format as defined in the API metadata.
Content type If the parameter data type is File, string(binary), or string(base64), specify the content type. Default values are application/json for JSON Conventional input documents, application/xml for BOD documents, and text/plain for ANY documents.
Value

To specify a constant value for all API calls for the form-data parameter on this row, define the value in this column. You can use keywords to specify the value.

See Keywords.
Path

To specify path expressions, select the option in this column. At runtime, the path expression is replaced with the value from the input document.

See Specifying a path for mapping.
Input Document

To send a complete input document as the value of the form-data parameter on this row, select the option in this column.

You can define how an input document is compressed.

  • No compression

    No compression is selected by default. The input document is sent without compression.

  • Deflate

    When Deflate is selected, the input document is compressed by using the deflate algorithm, as described in RFC 1951. The compression uses a combination of the LZ77 algorithm and Huffman coding wrapped in the zlib data format described in RFC 1950.

  • Deflate + Base64

    When Deflate + Base64 is selected, the input document is compressed by using the deflate algorithm and then Base64 encoded.

Configuring form-data parameters for binary file uploads

When the target API expects binary file content, for example, when uploading an image, configure the multipart/form-data request correctly.

  1. On the Request Body tab, select multipart/form-data as the request format.
  2. Locate the form-data parameter that represents the file, for example, a parameter named image with data type File.
  3. In the Content type column for this parameter, specify the actual media type of the file that you send, for example:
    • image/png for PNG images
    • image/jpeg for JPEG images
    • application/pdf for PDF documents
    • application/octet-stream for generic binary files
  4. Choose how to supply the file content:
    • Input Document column: Recommended for binary files. Select this option to send the complete input document as the value of the form-data parameter. To preserve the original binary format, use an ANY document as the input document type.
    • Path column: Use this option when the binary data is embedded in a structured document such as a BOD. Specify the path expression that points to the element that contains the file data, for example, Sync.MyFile/DataArea/MyFile/RawData. If the input document is a BOD, the extracted value is base64-encoded text.
    • Value column: Use this option only for static or keyword-based values. This option is not suitable for binary file content.
  5. Configure any additional form-data parameters, for example, a key or description parameter, by using the Value or Path columns as appropriate.
  6. Use the Test API Call function to verify that the request is accepted by the target API.

Example: Uploading a PNG image to an external API

This example demonstrates how to upload an image file to an external REST API that accepts multipart/form-data with a parameter named image.

Prerequisites:

  • The target API is registered in API Gateway with Swagger or OpenAPI specification.
  • The Swagger definition includes a POST operation with a multipart/form-data request body that contains a parameter named image of type File.
  • A service account with appropriate permissions is configured.

Steps:

  1. Create a new API Gateway connection point or edit an existing one.
  2. On the Documents tab, click Add and select the scenario Send to API or Trigger API.
  3. On the Input Document tab, select an ANY document as the input document. This ensures that the binary file is not base64-encoded.
  4. On the ION API tab, select the target API product and the POST operation for image upload.
  5. On the Request Body tab:
    • Select multipart/form-data as the request format.
    • In the Form Data Parameters list, locate the image parameter.
    • Set the Content type to image/png.
    • Select the Input Document option for this parameter.
  6. Click TEST to verify the configuration. Provide a sample PNG file as the test input document.
  7. Review the Response tab to confirm a successful response from the target API.

Alternative approach: Using a BOD with a modified API contract

If your data flow requires a BOD as the input document, for example, because the binary file is embedded in a Sync.MyFile BOD from a file connection, modify the target API Swagger definition to accept base64-encoded content.

  1. In the Swagger or OpenAPI definition for the target API, change the image form-data parameter type from binary or file to string.
  2. Re-import the updated Swagger definition into API Gateway and re-index the endpoints.
  3. In the API Gateway connection point, on the Request Body tab:
    • Select multipart/form-data as the request format.
    • For the image parameter, select the Path column option.
    • Specify the XPath to the base64 content in the BOD, for example, Sync.MyFile/DataArea/MyFile/RawData.
    • Set the Content type to match the expected format, for example, image/png, or adjust it to text/plain if the target expects a raw string.
  4. On the target side, implement logic to decode the base64 string back into binary before processing.
Note: This approach requires changes to both the API contract and the target application. Using an ANY document is simpler and is recommended when possible.