Variable references in API Connect

In API Connect you can reference different variables in your API definition.

When defining an API, creating a custom policy, or configuring another policy or logic construct, you can include references to context variables and properties.

Variable references are resolved either when the API is staged in a Product, for static variables that are fixed upon staging, or when the API is called, for variables that can change with each API call.

Types of variables

Context variables

A context variable is a variable relevant during an API call, for example, the input of the call, the path of the call, or the message during the call. A context variable is one of the variables that makes up that particular context.

Context variables can consist of more than one part, for example, request.headers.

For a list of available context variables, see API Connect context variables.

API properties

An API property is a variable in an API where its value depends upon the Catalog in which the API is staged or published. By referencing an API property, you can use the same API definition in different Catalogs where there are small differences between the instances of the API between the Catalogs. For example, an assembly could contain an if construct that executes its case when a particular Catalog is used, determined from the value of the API property. API properties can also be used to hide a value such as a password by encoding the value.

API properties are referenced by name.

For a list of API properties, see API properties

Note: Once defined, an API property is read only.
Catalog properties
A Catalog property is specific to a Catalog. and can be referenced in any of the API definitions in that Catalog. For more information, see Creating and configuring Catalogs.
Note:
  • If you change the value of a Catalog property, any API that references that property must be republished for it use the new value.
  • Catalog properties and API properties are not supported with global policies. Therefore, if you use such properties in a global policy, they are not replaced with the values specified in the Catalog or API property definitions.

Methods of referencing variables

You can get or set the value for a referenced variable.
GatewayScript references
When you want to reference a variable in a GatewayScript context, use one of the following methods:
apim.getvariable(variable)
where variable is the name of the context variable or API property that you want to reference.
apim.setvariable(variable, value, action)
where
  • variable is the name of the context variable or API property that you want to reference.
  • value is the string value that you want to set the variable to. This can be a literal value, or another variable. For example, to set your named variable to the value of the Content-Type header in a request, use the following code:
    var contentType = apim.getvariable('request.headers.content-type');
    apim.setvariable(variable, contentType, 'set');
    This property is required only when set or add is specified as the action.
  • action is the action that you want to apply to the variable. Valid options are:
    • set
    • add
    • clear
    If no option is set, the default option of set is applied.

Use the getvariable method to retrieve the value of a context variable or API property, and the setvariable method to change one.

Some of the situations where you would use this type of reference are:
  • GatewayScript policies. -For more information, see GatewayScript.
  • if logic constructs. For more information, see if.
  • User-defined policies. For more information, see Authoring policies.
Stylesheet references
You can reference a variable by using functions and elements in an XSLT policy with the following syntax:
<xsl:variable name="variable_name" select="apim:getVariable(variable)" />
where variable is a literal value, another variable, or a valid XSLT XPath statement.
<xsl:call-template name="apim:setVariable"> 
    <xsl:with-param name="varName" select="variable"/>
    <xsl:with-param name="value" select="value"/>
    <xsl:with-param name="action" select="action"/>
</xsl:call-template> 
where
  • variable is the name of the context variable or API property that you want to reference. This can be a literal value, another variable, or a valid XSLT XPath statement.
  • value is the string value that you want to set the variable to. This can be a literal value, another variable, or a valid XSLT XPath statement. This property is required only when set or add is specified as the action.
  • action is the action that you want to apply to the variable. This can be a literal value, another variable, or a valid XSLT XPath statement. Valid options are:
    • set
    • add
    • clear
    If no option is set, the default option of set is applied.
The following example sets a named variable to the value of the Content-Type header in a request:
<xsl:variable name="contentType" select="apim:getVariable('request.headers.content-type')" />
<xsl:call-template name="apim:setVariable"> 
    <xsl:with-param name="varName" select="'variable'"/>
    <xsl:with-param name="value" select="$contentType"/>
    <xsl:with-param name="action" select="'set'"/>
</xsl:call-template>
Inline references
In many situations you can make a simpler reference, by using the following syntax:
$(variable)
where variable is the name of the context variable or API property that you want to reference.
Some of the situations where you would use this type of reference are:
  • The URL called by an Invoke or Proxy policy. For more information about the policies, see Invoke or Proxy.
  • A Map policy. For more information, see Map.
Note: The map policy can reference the following variables inline:
  • Variables that are defined as inputs to the map policy and specified in the from field of a mapping.
  • Context variable or API properties, provided that the x-ibm-gateway-map-resolve-apic-variables API property is not set to false. If an inline reference in a map policy resolves to a context variable or API property, it is immediately replaced by the corresponding value. For more information on the x-ibm-gateway-map-resolve-apic-variables API property, see Properties controlling the map policy.
For more information on the use of inline references, and examples, see the following About inline references section.

About inline references

When you use an inline reference for a property value in an assembly policy, the variable reference is replaced with the corresponding string value at run time, before the property is evaluated. For example, consider the following incoming request, which has two headers and two query parameters (a curl command is used to illustrate the request):
curl --data-binary @request.json \
   -H 'Content-Type: application/json' \
   -H 'X-Environment: test' \
   http://apiserver/org/catalog/petstore/getPetDetails?petid=285&storeid=z03
If an invoke policy is configured as follows:
 invoke:
    target-url: https://backend/GetPetInfo/$(request.parameters.storeid)/$(request.parameters.petid)
then the value of the target-url property is evaluated as https://backend/GetPetInfo/z03/285, and this is therefore the URL to which the invoke policy sends its request.
DataPower Gateway (Classic)
onlyYou can also use an inline reference in the condition property of a switch policy. Consider the following example:
- switch:
    case:
        - condition: "$(request.headers.X-Environment)" == "production"
            execute:
                - invoke:
                    http://www.finance.com/base/stockquote
        - condition: "$(request.headers.X-Environment)" == "test"
            execute:
                - invoke:
                    http://testserver1.finance.com/stockquote
Using the incoming request referred to previously, the value of the X-Environment header is "test". The inline references are first evaluated, then the conditions are evaluated as JavaScript. Therefore, the first condition is evaluated as "test" == "production", returning false, and the second condition is evaluated as "test" == "test", returning true, so the invoke policy sends its request to http://testserver1.finance.com/stockquote.
Important: This example, which encloses the inline references inside double quotes, assumes that the API is deployed to the DataPower API Gateway. If you deploy the API to the DataPower Gateway (v5 compatible), then the double quotes are added implicitly when the inline references are evaluated, and you must therefore omit them from the condition property; the two conditions in this example would therefore be
condition: $(request.headers.X-Environment) == "production"
and
condition: $(request.headers.X-Environment) == "test"
However, as an alternative to using an inline reference in a condition, you can instead use pure JavaScript, as follows:
- switch:
    case:
        - condition: request.headers["X-Environment"] == "production"
            execute:
                - invoke:
                    http://www.finance.com/base/stockquote
        - condition: request.headers["X-Environment"] == "test"
            execute:
                - invoke:
                    http://testserver1.finance.com/stockquote
in which case the policy configuration will work correctly as-is in both types of gateway.

For more information on the types of gateway, see API Connect gateway types.

In addition to single strings, you can use an inline reference for a complete object. Consider the following example, which uses an inline reference in a set-variable policy:
- set-variable:
    actions:
        - set: saved.reqHdrs
           value: $(request.headers)
           type: string
Here, the request.headers structured JSON object is substituted with its corresponding string representation, and a variable named reqHdrs is therefore created, under the saved object, with a string value of {"Content-Type":"application/json","X-Environment":"test",...}. However, if you are using the DataPower API Gateway, you can specify type: any, in which case the set-variable policy copies the value as-is, and saved.reqHdrs is created as a JSON object rather than a string:
- set-variable:
    actions:
        - set: saved.reqHdrs
           value: $(request.headers)
           type: any
You can reference a property in a JSON or XML request directly by name, by using the following syntax:
$(request.body.property_name)
For example, if the request contains { "account-number": 123 } or <account-number>123</account-number> you can retrieve the value 123 by using the following inline reference:
$(request.body.account-number)
If the property value is within a nested property structure, you can reference it by concatenating the property names. For example, if the request contains { "account": { "balance": 123 } } or <account><balance>123</balance></account> you can retrieve the value 123 by using the following inline reference:
$(request.body.account.balance)
Similarly, you can reference a property in a JSON or XML response by using the following syntax:
$(message.body.property_name)
Restriction: If you are using the DataPower API Gateway, you can reference properties in this way only if the format of the request or response is JSON; the mechanism is not supported with XML request or response formats. If the you are using the DataPower Gateway (v5 compatible) the mechanism is supported with both JSON and XML formats.