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

For more information, see Setting API properties.

Methods of referencing variables

You can get or set the value for a referenced variable.

Get the value for a variable in either of the following ways:
- Through the GatewayScript policy, run the apim.getvariable() API.
- Through the XSLT policy, run a stylesheet that uses the apim:getVariable extension function.
- In an assembly policy field that supports variable references, use the following syntax:
```
$(variable)
```
Set the value for a variable in either of the following ways:
- Through the Set Variable policy.
- Through the GatewayScript policy, use the apim.setvariable() API.
- Through the XSLT policy, run a stylesheet that uses the apim:setVariable extension element.

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 and JavaScript policies. For more information, see GatewayScript (gatewayscript) and JavaScript (javascript).
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 (invoke) or Proxy (proxy).
A Map policy. For more information, see Map (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.