Referenceable Variable in API Connect

This topic provides information about variables that can be defined and or accessed at runtime in API Connect.

These variables exists in the API Connect environment during the execution of the APIC assembly.
The assembly is the definition of the processing flow that is executed by the API Gateway at runtime when a request is received. This processing flow consists of policies and these can be "validate", "map", switch, javascript, xslt, invoke, ...

These variable can be referenced in APIC policies using the notation $(varName). For example in a invoke policy, you might want to evaluate dynamically the host name or the URL:

In this snapshot, the "backendurl" and the "payid" are variable that are referenced.

What are the variable that can be defined and referenced?

There are two main type of variables: context variable and API properties.
Context variables are variables that the value usually depends of the message request whereas API properties have their values defined when the API is published.

There are three main subcategories (my interpretation) of context variables:

• user variables: these variables are defined in the assembly using javascript, xslt, or set variable
• policies variables: these variables are instantiated by the policy that you set on the assembly. For example the validate policy creates context variable "decoded.claims" (validate jwt).
• apic environment variables: these variables are set by the apic environment. For example the variable message (corresponds to the current data on the flow) and the request (corresponds to the input message and should be considered immutable).

How can these variables be accessed/defined ?

API Properties

API properties are defined by the "properties" in the API design UI (or the yaml). The value of these variables may differ depending on which catalog the API is published. 

This can be useful if for example within the same APIC cloud environment different catalogs are defined for different environment (f.e. DEV, TEST). You can for example define a "backendurl" that would be different if the API is deployed in the DEV catalog or in the TEST catalog.

These variable are accessed at runtime the same way as context variable using the notation $(myPropertyVar) or in a gatewayscript/xslt using the getvariable function (more later).

Context Variables

Unless set by the runtime, context variables are set programatically using either the setVariable, the gatewayscript (javascript) or the xslt policy.

In gatewayscript or xslt the variables are accessed using a provided getVariable or setVariable function.

Using gatewayscript:

apim.setvariable('payid',myvar,'set');
apim.getvariable('paid');

or using xslt:

<?xml version="1.0" encoding="UTF-8"?>
<xsl:stylesheet version="1.0"
  xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
  xmlns:dp="http://www.datapower.com/extensions"
  xmlns:func="http://exslt.org/functions"
  xmlns:apim="http://www.ibm.com/apimanagement" extension-element-prefixes="dp func apim">
  <!-- Contains the APIM functions -->
  <xsl:import href="local:///isp/policy/apim.custom.xsl" />
  <xsl:template match="/">
    <xsl:call-template name="apim:setVariable">
      <xsl:with-param name="varName" select="'payid'" />
      <xsl:with-param name="value" select="'avalue'" />
    </xsl:call-template>
    <xsl:message>
      <xsl:text>Variable [</xsl:text>
      <xsl:value-of select="'payid'" />
      <xsl:text>] set to [</xsl:text>
      <xsl:value-of select="'avalue'" />
      <xsl:text>]</xsl:text>
    </xsl:message>
  </xsl:template>
</xsl:stylesheet>

More example can be found here for gatewayscript or for xslt.

Available runtime context variable

A list of runtime context variable that you can access are provided here at the knowledge center.

Notes that even when the API Gateway is DataPower, only the API runtime context variable can be reached. You can't for example access DataPower service variable.
If you would like to access them, you would need to create an APIC custom policy that would use either a gatewayscript action or xsl action to set an APIC environment variable using the apim set variable (using as example the snippet code provided before).