Skip to content

API Parameters Configuration Guide

InfoConnect Hub reads the value of each API parameter from the incoming HTTP request. The Source Field Name property of a parameter defines where the Hub looks for the value: the request body, an HTTP header, a URI path variable or a query parameter. The same mechanism applies to Program Calls, Data APIs and RPA Calls.

If a parameter has no request source prefix, the Hub reads the value from the request body. If the body has no such field, the Hub looks for a query parameter and then a header with that name. For example, both of the following values are body mappings:

customerId
$['customerId']

Supported request sources

Source Description Supported syntax
Body JSON request body customerId, message.body.customerId, $['customerId'], $['message.body.customerId']
Headers HTTP request headers message.headers.customerId, $['message.headers.customerId']
URI parameters Variables defined in the request URI message.uriParams.customerId, $['message.uriParams.customerId']
Query parameters URL query string parameters message.queryParams.customerId, $['message.queryParams.customerId']

Request body

Map a parameter to a field of the JSON request body. For a field named status, use any of these values as Source Field Name:

  • status
  • message.body.status
  • $['message.body.status']

Request example:

{
  "status": "BODY_ST",
  "event_name": "BODY_EVENT_NAME"
}

The request body is the recommended source for both simple fields and complex STRUCTURE parameters.

HTTP headers

Map a parameter to an HTTP request header. For a header named customerId, use either of these values as Source Field Name:

  • message.headers.customerId
  • $['message.headers.customerId']

Request example:

POST /api/test-data-api/headers
Authorization: Bearer eyJhbGciOiJIUzI1NiJ9
Content-Type: application/json
customerId: 12345

Structures in headers

Headers are not well suited to STRUCTURE parameters, but you can pass them in a flattened form with indexed field names and dot notation:

orderItemsIn_0.item: ITEM1
orderItemsIn_0.qty: 123.45
orderItemsIn_0.price: 321.45
orderItemsIn_1.item: ITEM2
orderItemsIn_1.qty: 234.45
orderItemsIn_1.price: 987.45

Use this style only when a structured value must be passed without a request body. For large objects, use the request body.

URI parameters

Map a parameter to a variable of the request URI. The variable must be part of the URI configured for the Functional API. For example, for the parameter message.uriParams.orderID, configure the URI as follows:

/api/uri/{orderID}

Separate multiple variables with slashes:

/api/uri/{orderID}/{orderLines}

Use either of these values as Source Field Name:

  • message.uriParams.orderID
  • $['message.uriParams.orderID']

Request example:

GET /api/uri/12345

Query parameters

Map a parameter to a query string parameter. For a parameter named status, use either of these values as Source Field Name:

  • message.queryParams.status
  • $['message.queryParams.status']

Request example:

GET /api/query?status=QUERY_STATUS

Structures in query parameters

For complex structures such as arrays or objects, use indexed notation. Use dot notation for nested objects and _0, _1, _2 and so on for array items:

param_0.inner=value1&param_1.inner=value2

Example for the structured parameter orderItemsIn:

GET /api/custom/uri/query?orderID=12345&orderLines=10&orderItemsIn_0.item=ITEM1&orderItemsIn_0.qty=123.45&orderItemsIn_0.price=321.45

This request is equivalent to the following JSON request body. Values from the query string arrive as strings:

{
  "orderID": "12345",
  "orderLines": "10",
  "orderItemsIn": [
    {
      "item": "ITEM1",
      "qty": "123.45",
      "price": "321.45"
    }
  ]
}

Using structures

You can map STRUCTURE parameters from any supported request source except the URI parameters.

Place complex structures in the request body whenever possible. You can reconstruct nested values from headers or query parameters, but these request components are intended for small pieces of metadata, not for large object graphs. Use flattened STRUCTURE mapping through headers or query parameters only when necessary.

Mapping rules

  • Body fields can be referenced in the short form (customerId) or the fully qualified form (message.body.customerId).
  • URI parameters always need the message.uriParams. prefix. Use the message.headers. and message.queryParams. prefixes to read a header or query parameter explicitly.
  • Plain notation and bracket notation ($['...']) are both supported.
  • Nested request body properties are fully supported.

Request validation

Before the Hub calls the IBM i, it validates the values of the incoming request against the parameter definitions of the API. This applies to Program Calls, Data APIs and RPA Calls. If the request is invalid, the Hub returns HTTP 400 with all problems found and does not call the IBM i. The API is not marked as FAILED.

Request validation is disabled by default, so existing APIs are not affected. To switch it on for an API, set schemaValidationEnabled to true in the API definition. In the web UI, select the Schema validation checkbox of the Program Call, Data API or RPA Call form.

{
  "programDefinitionName": "lookup",
  "schemaValidationEnabled": true
}

What is validated

Parameters with the OUT usage are not validated. The Hub checks IN and INOUT parameters as follows:

Check Rule
Required value The value resolved through sourceFieldName must be present. For Program Calls with optionalFields set to true, a missing value is skipped, but a value that is present is still checked. Data API variables are required unless the variable has a default value.
Data type The value must match the parameter dataType. Numeric types (BIGINTEGER, BINARY, BYTEARRAY, FLOAT, INTEGER, PACKED, SHORT, ZONED) must be numbers. Text types (DATE, TIME, TIMESTAMP, STRING, UNSIGNEDBINARY) are accepted as text; numbers and booleans are converted to text.
Length When length is greater than 0, the length of the value must not exceed it.
Decimal positions For PACKED and FLOAT the number of fractional digits must not exceed decimalPositions, and the value must fit into the configured length (for example, length 5 with 0 decimal positions allows up to 99999, length 7 with 2 decimal positions allows up to 99999.99).
Structures A STRUCTURE is validated through its elements. The value must be a JSON object or an array of objects, and the number of elements must not exceed count. Elements are reported with their position, for example orderLinesIn[1].qty.

RPA Calls are validated in the same way, except that when a parameter has no dataType, only its maximum length is checked.

Error response

The response has HTTP status 400 and a single message field. All problems are listed in the message, separated by ;.

{
  "message": "Parameter 'customerName' exceeds maximum length 10 (actual length 13).; Parameter 'limit': value is incompatible with type PACKED (got abc)."
}

The message texts are:

Problem Message
Missing value Parameter '<name>' is required but was not provided. (for a Data API: Variable '<name>' is required but was not provided.)
Wrong type Parameter '<name>': value is incompatible with type <TYPE> (got <value>).
Value too long Parameter '<name>' exceeds maximum length <n> (actual length <m>).
Too many decimals Parameter '<name>': value <value> has <k> fractional digit(s) but at most <d> allowed (decimalPositions).
Value too large Parameter '<name>': value <value> exceeds maximum <max> for <TYPE> (length <l>, decimalPositions <d>).
Too many structure elements Parameter '<name>': at most <n> elements allowed (got <m>).
Invalid structure value Parameter '<name>': nested STRUCTURE must be a JSON object or a JSON array of objects; received <type>.
Unknown or missing data type Parameter '<name>': unknown data type '<type>'. and Parameter '<name>': data type is not set.