API properties

Your APIs are configured by using properties.

Properties are used by the gateway to control behavior of certain policies. Typically, you provide properties, but the policy can also provide properties settings. In API Connect, you can create API properties that consist of Catalog-specific values to eliminate the need for source code modifications. You can then reference the properties elsewhere in your API definition. API properties for the invoke, map, proxy, and rate limit policies are shown in the tables.

A list of invoke related API properties that control the behavior of the invoke policy.
Table 1. Properties controlling the invoke policy
Property Required Description Data type
[V5.0.6 or later]x-ibm-gateway-decode-request-params [V5.0.6 or later]No [V5.0.6 or later]From API Connect version 5.0.6.2 onward: If set to a value of true, any request parameters that are referenced by a variable definition on an invoke target-url are URL-decoded. This replicates the behavior from before release 5.0.6.2. From release 5.0.6.2 and beyond, the default behavior is to not decode any parameters, thereby sending them to the target URL without alteration. [V5.0.6 or later]Boolean
[V5.0.6 or later]x-ibm-gateway-invoke-suppress-clientid [V5.0.6 or later]No [V5.0.6 or later]From API Connect version 5.0.6.3 onward: When set with a value of true, or not specified, the X-IBM®-Client-Id HTTP header (if specified on the API request) is suppressed from being sent to the invoke target URL. When set with a value of false, the X-IBM-Client-Id HTTP header is no longer suppressed from being sent to the invoke target URL. [V5.0.6 or later]Boolean
[V5.0.8 or later]x-ibm-gateway-queryparam-encode-plus-char [V5.0.8 or later]No [V5.0.8 or later]From API Connect version 5.0.8.3 onward: If set to a value of true, all + characters in the query parameter values of the target-url of the Invoke and Proxy policies are encoded to %2F.

The default value is false.

In previous releases, + were always encoded to %2F. Now, the default behavior is to not do the encoding.

 [V5.0.8 or later]Boolean
[V5.0.8 or later]x-ibm-gateway-api-enforce-response-limits [V5.0.8 or later]No [V5.0.8 or later]From API Connect version 5.0.8.3 onward: If set to a value of true, allows the JSON parser to be enforced on the response rule. If the response body size is higher than the JSON parser limit set in the DataPower® domain, a status code of 500 is returned. [V5.0.8 or later]Boolean
[V5.0.8 or later]x-ibm-gateway-invoke-emulate-v4-soap-error [V5.0.8 or later]No [V5.0.8 or later]From API Connect version 5.0.8.3 onward: IBM API Management Version 4.0 initiates a DataPower error when a SOAP fault is returned from a web service. IBM API Connect provides a mechanism to catch SOAP errors and does not initiate a DataPower error. For compatibility with APIs developed in IBM API Management Version 4.0, set this property to true only in the case where a gateway extension is expecting to handle a SOAP error in a post error rule.

The default value is false.

Note: From API Connect version 5.0.8.8 onward: This property is deprecated in favor of x-ibm-gateway-invoke-emulate-v4-invoke-error.
 [V5.0.8 or later]Boolean
[V5.0.8 or later]x-ibm-gateway-invoke-keep-payload [V5.0.8 or later]No [V5.0.8 or later]From API Connect version 5.0.8.5 onward: If set to a value of true, the invoke policy sends a payload on an HTTP DELETE method. This property is available for use with IBM DataPower Gateway version 7.7.1.1 and later.

The default value is false.

 [V5.0.8 or later]Boolean
[V5.0.8 or later]x-ibm-gateway-invoke-emulate-v4-invoke-error [V5.0.8 or later]No [V5.0.8 or later]From API Connect version 5.0.8.8 onward: IBM API Management Version 4.0 initiates a DataPower error when a backend server error is returned, either a SOAP fault returned from a web service or a JSON or XML (non-SOAP) error from a restful service. IBM API Connect provides a mechanism to catch SOAP errors and operation errors and does not initiate a DataPower error when they occur. If no catch policy is configured, a generic error message is generated. For compatibility with APIs developed in IBM API Management Version 4.0, set this property to true only in the case where a gateway extension is expecting to handle a backend server error in a gateway extension POST error rule or if the client of the API is expecting the backend server error to be returned.

The default value is false.

 [V5.0.8 or later]Boolean
A list of map-related API properties that control the behavior of the map policy.
Table 2. Properties controlling the map policy
Property Required Description Data type
[V5.0.7 or later]x-ibm-gateway-map-array-first-element-value [V5.0.7 or later]No [V5.0.7 or later]From API Connect version 5.0.7.2 onward: In IBM API Management Version 4.0, if a mapping source value is from an array then only the first value is output. In API Connect, the default behavior is to return an array of all array element values. To maintain compatibility with IBM API Management Version 4.0, set this API property to true to only return the first array element value. [V5.0.7 or later]Boolean
[V5.0.7 or later]x-ibm-gateway-map-resolve-apic-variables [V5.0.7 or later]No [V5.0.7 or later]From API Connect version 5.0.7.2 onward: By default, any API Connect variable that is found in the map configuration is resolved. For example, $(request.headers.content-type) resolves to the request's content type header. Because searching for variables in every map property can be CPU intensive, you can choose not to resolve variables by setting this API property to false. If this property is not configured or is set to any other value, the existing behavior to search for these variables continues. Note that variable usage within a map value JavaScript snippet is not changed provided that the variables that are referenced come from a configured map input. [V5.0.7 or later]Boolean
[V5.0.8 or later]x-ibm-gateway-map-create-empty-array [V5.0.8 or later]No [V5.0.8 or later]From API Connect version 5.0.8.1 onward: This property controls how the map policy handles the output of an empty array; it can have the following values:
  • all: Output all empty arrays, including empty children arrays. This is the default value if the property is not configured or has an invalid value.
  • parent: Output only the current property's empty array value. Children map actions of this property are not attempted.
  • none: Prevent any empty output array values from being produced.
 [V5.0.8 or later]String
[V5.0.8 or later]x-ibm-gateway-optimize-schema-definition [V5.0.8 or later]No [V5.0.8 or later]From API Connect version 5.0.8.3 onward: Set the value of this property to true to provide a performance improvement to the map policy when a very complex schema definition is referenced by a policy output definition; for example, some very complex schemas that are generated by importing a very complex WSDL schema.

The map policy builds a schema from an API definition when a referenced definition is provided as the value of the schema. If the schema does not have references that generate a circular reference, setting this property to true might provide a performance benefit while generating the same schema as would otherwise have been generated. However, in cases where the schema is very complex, with many potentially circular references, the generated schema could be different because the enhanced schema handling processes circular references differently. In such cases therefore, you should examine the resulting output to determine if the performance benefit gained is not at the expense of a change in the map policy output.

The default value of this property, is false, maintaining the existing behavior and performance.

 [V5.0.8 or later]Boolean
[V5.0.8 or later]x-ibm-gateway-map-null-value [V5.0.8 or later]No [V5.0.8 or later]From API Connect version 5.0.8.4 onward: Set the value of this API property to true to allow a property from a map policy's input data with a value of null to be mapped to the output document. By default, a property from a map policy's input data with a value of null is not mapped to the output document. [V5.0.8 or later]Boolean
[V5.0.8 or later]x-ibm-gateway-map-resolve-xmlinput-datatypes [V5.0.8 or later]No [V5.0.8 or later]From API Connect version 5.0.8.5 onward: XML input elements with numeric or boolean data have no metadata to indicate whether this data should be mapped as a string value or as the specific data type. If you set the value of this property to false, XML input elements are always mapped as a string. If you set the value to true, numeric or boolean XML input elements are mapped as the corresponding data type from the input schema.

The default value is false.

 [V5.0.8 or later]Boolean
[V5.0.8 or later]x-ibm-gateway-map-xml-empty-element [V5.0.8 or later]No [V5.0.8 or later]From API Connect version 5.0.8.5 onward: This property controls how the map policy handles XML input empty elements and impacts JSON output when the input document is XML; it can have the following values:
  • string: The value for an empty XML element is considered to be an empty string. This is the default value if the property is not configured or has an invalid value.
  • null: The value for an empty XML element is considered to be null. A mapping of this element to a JSON output property does not occur unless the API property x-ibm-gateway-map-null-value is also specified with a value of true.
  • none: The empty XML element is ignored.
  • From API Connect version 5.0.8.10 onward: string-badgerfish: The value for an empty XML element is considered to be an empty string. The empty string value will be placed into a JSON badgerfish value property.
  • From API Connect version 5.0.8.10 onward: null-badgerfish: The value for an empty XML element is considered to be null. The null value will be placed into a JSON badgerfish value property. A mapping of this element to a JSON output property does not occur unless the API property x-ibm-gateway-map-null-value is also specified with a value of true.
 [V5.0.8 or later]Boolean
[V5.0.8 or later]x-ibm-gateway-schema-definition-reference-limit [V5.0.8 or later]No [V5.0.8 or later]From API Connect version 5.0.8.5 onward: Set the value of this property to an integer value that specifies the maximum allowed number of iterations of a circular schema definition.

The default value is 1, which means that circular schema definitions are not followed. The maximum possible value is 5. If you specify a value greater than 5, a value of 5 is assumed. If you specify a non-numeric value, a value of 1 is assumed.

 [V5.0.8 or later]String
[V5.0.8 or later]x-ibm-gateway-map-emulate-v4-default-required-properties [V5.0.8 or later]No [V5.0.8 or later]From API Connect version 5.0.8.7 onward: Set the value of this property to true to have default values generated in the output for required properties that are either not mapped, or for which there is no input data present, in the following specific cases:
  • An array consists of objects that contain one or more required properties.
  • An object which is optional has one or more child properties that are required.

By default, these required properties are not present in the output. If you set the x-ibm-gateway-map-emulate-v4-default-required-properties API property to true, these required properties will be present in the output. If the output schema defines a default property for the output property then the specified default value is used, otherwise a default value is assigned dependent on the data type, as follows:

  • String: empty string ("")
  • Number: 0
  • Boolean: false
  • Object: empty object
  • Array: empty array
Example 1
The input data has the following array of objects:
[{“a”: “value1”}, {“a”: “value2", "b": “value3”}]

The output schema defines the output object as having two properties, a and b, of which b is required. The map policy defines the following mappings:

  • input.array.a to output.array.a
  • input.array.b to output.array.b

If the x-ibm-gateway-map-emulate-v4-default-required-properties API property is set to true, and b is either not mapped or has no input data present, then b is assigned a default value of an empty string, and the output is as follows:

[{“a”: “value1", "b": ""}, {"a": "value2", "b": "value3"}]
Example 2
The output schema defines the following structure:
{"a" : {"b" : {"c" : "value1", "d" : "value2"} } }

Property b is optional but property d within b is required.

The map policy defines a mapping to output.a.b.c.

If the x-ibm-gateway-map-emulate-v4-default-required-properties API property is set to true, and d is not mapped, then d is assigned a default value of an empty string, and the output is as follows:

{"a" : {"b" : {"c" : "value1", "d" : ""} } }

If the x-ibm-gateway-map-emulate-v4-default-required-properties API property is not specified or does not have a value of true, these required properties are not created in the output with their default values.

 [V5.0.8 or later]Boolean
[V5.0.8 or later]ibm-gateway-map-post-process-json-output [V5.0.8 or later]No [V5.0.8 or later]From API Connect version 5.0.8.8 onward: Set the value of this property to true to enable post processing of mapped JSON output. The post processing of JSON output will use the output schema to ensure that property values are of the same data type as that defined in the schema. It will also normalize output property values that have a Badgerfish JSON syntax due to object mapping of an XML input. Set the value to false for no post processing of mapped JSON output.

The default value is false.

 [V5.0.8 or later]Boolean
[V5.0.8 or later]x-ibm-gateway-map-emulate-v4-empty-json-object [V5.0.8 or later]  [V5.0.8 or later]From API Connect version 5.0.8.7 onward: If a mapping fails because its input is not present and there is no default mapping configured, the default behavior is to not to make any change to the output mapping. Set the value of this property to true to create an empty object for the parent of the target mapping, emulating the behavior of IBM API Management Version 4.0.
Example
The map policy defines a mapping to output.a.b.c.
If input data is present, the output is as follows:
{
  "a": {
    "b": {
      "c": "inputvalue"
    }
  }
}
If there is no input data, and the x-ibm-gateway-map-emulate-v4-empty-json-object API property is set to true, the output is as follows:
{
  "a": {
    "b": {
    }
  }
}
Properties a and b are created but the value of b is an empty object.

The default value is false.

 [V5.0.8 or later]Boolean
A list of proxy-related API properties that control the behavior of the proxy policy.
Table 3. Properties controlling the proxy policy
Property Required Description Data type
[V5.0.6 or later]x-ibm-gateway-proxy-suppress-clientid [V5.0.6 or later]No [V5.0.6 or later]From API Connect version 5.0.6.3 onward: A setting of false activates the injection of the X-IBM-Client-Id HTTP header (if it is specified on the API request), or the client_id query parameter in the request URL, to the proxy target-url. If set with a value of true, suppresses the sending of this header or parameter on the proxy target-url. If not specified, this header is suppressed, but the parameter is not suppressed on the proxy target-url.

In previous releases, the client ID parameter was always suppressed.

 [V5.0.6 or later]Boolean
[V5.0.8 or later]x-ibm-gateway-optimize-invoke [V5.0.8 or later]No [V5.0.8 or later]If set to false, prevents the replacement of the last invoke in a policy with proxy. Any value other than false (case insensitive) will result in the last invoke in a policy possibly being replaced by proxy when the API is executed in the gateway. [V5.0.8 or later]Boolean
[V5.0.8 or later]x-ibm-gateway-queryparam-encode-plus-char [V5.0.8 or later]No [V5.0.8 or later]From API Connect version 5.0.8.3 onward: If set to a value of true, all + characters in the query parameter values of the target-url of Invoke and Proxy policies are encoded to %2F.

The default value is false.

In previous releases, + were always encoded to %2F. Now, the default behavior is to not do the encoding.

 [V5.0.8 or later]Boolean
[V5.0.8 or later]x-ibm-gateway-api-enforce-response-limits [V5.0.8 or later]No [V5.0.8 or later]From API Connect version 5.0.8.3 onward: If set to a value of true, allows the JSON parser to be enforced on the response rule. If the response body size is higher than the JSON parser limit set in the DataPower domain, a status code of 500 is returned. [V5.0.8 or later]Boolean
A list of API properties that control the behavior of the rate limit policy.
Table 4. Properties controlling the rate limit policy
Property Required Description Data type
[V5.0.8 or later]x-ibm-gateway-emulate-v4-plan-rate-limit [V5.0.8 or later]No [V5.0.8 or later]From API Connect version 5.0.8.4 onward: By default in IBM API Connect Version 5.0, if you configure a rate limit only for a Plan and not for the API operations within the Plan then a single rate limit threshold is set for the API as a whole, regardless of which operation in the API is requested. This behavior differs from IBM API Management Version 4.0 where the rate limit is set individually for each operation in the API. To change the Version 5.0 behavior to emulate the Version 4.0 behavior, set this API property to a value of true. [V5.0.8 or later]Boolean
A list of API properties that control the behavior of multiple policies.
Table 5. Properties controlling multiple policies
Property Required Description Data type
[V5.0.8 or later]x-ibm-gateway-sourcecode-resolve-apic-variables [V5.0.8 or later]No [V5.0.8 or later]From API Connect version 5.0.8.5 onward: If set to true, API Connect variable references are resolved. Set to false if you want the policy to ignore API Connect variable references.

The default value is true.

This property applies to the following policies:
  • GatewayScript
  • XSLT
  • Map
  • if
  • switch
Note: This property setting is overridden by the x-ibm-gateway-map-resolve-apic-variables API property setting for the Map policy.
 [V5.0.8 or later]Boolean
[V5.0.7 or later]x-ibm-gateway-api-json-parse-error-handling [V5.0.7 or later]No [V5.0.7 or later]From API Connect version 5.0.8.7 iFix3 onward: If an API request or response payload includes valid JSON content that contains characters that cannot be represented in the JSONX XML internal syntax that is used by the DataPower Gateway, set this property to escape-unicode to allow the payload to be accepted without parsing errors. If this property is not configured or is set to any other value, the payload is rejected as invalid JSON.

This property applies to the API request payload, and to the API response payload when x-ibm-gateway-api-enforce-response-limits is enabled.

 [V5.0.7 or later]String
[V5.0.8 or later]x-ibm-gateway-framework-preserve-escaped-reverse-solidus [V5.0.8 or later]No [V5.0.8 or later]From API Connect version 5.0.8.8 onward: By default, the string \\ in a policy property is converted to a single \ character. Set this property to true to preserve the string \\. [V5.0.8 or later]Boolean
[V5.0.8 or later]x-ibm-gateway-inspect-request-headers [V5.0.8 or later]No [V5.0.8 or later]From API Connect version 5.0.8.10 onward: Causes an inspection of the HTTP headers in the API request to check for characters in the header values that are illegal XML characters; it can have the following values:
  • default: There is no inspection for these characters in the header values. If one is present, the API request fails with an HTTP 500 Internal Server Error.
  • sanitize: Any illegal XML characters in header values are replaced with a ? character. The API processing will continue. Any API that attempts to read request.headers.<headername> will see the ? character in the value. However, the original protocol headers representing message.headers will still have the original character, which will be sent to an invoke or proxy backend server.
  • bad-request: There will be an inspection for these characters in the header values. If one is present, the API request fails with an HTTP 400 Bad Request.

The default value is default.

 [V5.0.8 or later]Boolean
A list of API properties that control the behavior of custom policies.
Table 6. Properties controlling custom policies
Property Required Description Data type
[V5.0.8 or later]x-ibm-gateway-custom-policy-with-gws-action [V5.0.8 or later]No [V5.0.8 or later]From API Connect version 5.0.8.4 onward: If set to true, the request.body and message.body context variables will be populated for access by an apim.getvariable('request.body') or apim.getvariable('message.body') function call in a GatewayScript action of a custom policy. If the custom policy does not use a GatewayScript action that requires these variables to be populated, set this property to false or do not specify it.

The default value is false.

 [V5.0.8 or later]Boolean