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:
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:
statusmessage.body.status$['message.body.status']
Request example:
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:
Separate multiple variables with slashes:
Use either of these values as Source Field Name:
message.uriParams.orderID$['message.uriParams.orderID']
Request example:
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:
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:
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 themessage.headers.andmessage.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.
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. |