Using context variables in GatewayScript and XSLT policies with the DataPower API Gateway

Introduction

All API context variables are stored in a JSON-like tree; each context variable is a node in this tree. A non-leaf node can be either an object or an array, while a leaf node can be a number, string, boolean, or document; a document can contain an XML document, BLOB, Stream, or another JSON document.

Each context variable has a name and a value. You can access a context variable by name when using the GatewayScript and XSLT APIs. Dot notation is used to access a context variable, reflecting the position of the corresponding node in the JSON-like tree; for example, request.headers.Host. Where a node name contains special characters, bracket notation is supported; for example, request.headers['Content-Type'].

For the GatewayScript policy, all the APIs for the DataPower® API Gateway are in the context module, which is a global module. You can therefore access the context module directly, you do not need to use the require() function first.

For the XSLT policy, the APIs are in the http://www.ibm.com/xmlns/datapower/2017/11/apigateway namespace; to use these APIs you must declare this namespace.

Accessing context variables - examples

GatewayScript examples

To read the client.app.id context variable:

var clientID = context.get('client.app.id');

To set the value of a context variable:

context.set('my.vars.amount', 100);

The resulting tree has the following structure:

{ "my": { "vars": { "amount": 100 } } }

To delete the node my.vars, and all its child nodes:

context.clear('my.vars');

The resulting tree has the following structure:

{ "my": { } }

XSLT examples

To read the client.app.id context variable:

<xsl:variable name="clientID" select="apigw:get-variable('client.app.id')"/>

To set the value of a context variable:

<apigw:set-variable name="'my.vars.amount'" value="100"/>

The resulting tree has the following structure:

{ "my": { "vars": { "amount": 100 } } }

To delete the node my.vars, and all its child nodes:

<apigw:clear-variable name="'my.vars'"/>

The resulting tree has the following structure:

{ "my": { } }

About payloads

{
  "headers": {
    "Content-Type": "application/xml",
    "X-Client-ID": "1234567890"
  },
  "variables": {
    "amount": 123,
    "name": "xyz"
  },
  "status": {
    "code": 200,
    "reason": "OK"
  },
  "body": <XML/Blob/Stream/JSON Document>
}

Manipulating the message headers - examples

GatewayScript examples

To delete a header:

context.message.header.remove('X-My-Header');

To read a header:

var reqType = context.request.header.get('Content-Type');
var currType = context.message.header.get('Content-Type');

To set a header:

context.message.header.set('Content-Type', 'application/json');

To iterate through the headers:

var reqHdrs = context.request.headers;
for (var h in reqHdrs) {
   console.log('>>> Reading the request header: ', h, '=', reqHdr[h]);
} 

var currHdrs = context.message.headers;
for (var h in currHdrs) {
   console.log('>>> Reading the current header: ', h, '=', currHdr[h]);
} 

To create a message context called headersContext, if one doesn't already exist, and add to it a boolean context variable called HelloWorld, with the value true:

var ctx = context.getMessage("headersContext") || context.createMessage("headersContext");
ctx.setVariable('HelloWorld', true);

The setVariable call writes the variable into headersContext.variables.HelloWorld; therefore a condition statement in any subsequent switch policy should check for headersContext.variables.HelloWorld rather than headersContext.HelloWorld.

To read the context variable in any subsequent gatewayscript policy, use the following call:

ctx.getVariable("HelloWorld")

Note: If you are either migrating an API from IBM® API Connect Version 5.0, or from the DataPower Gateway (v5 compatible), to the DataPower API Gateway, or you are configuring a new API for the DataPower API Gateway, creating a message context, rather than using the context variable mechanism described in Accessing context variables - examples, is the preferred option. In the case of migration, it most closely matches the behavior of IBM API Connect Version 5.0, and setVariable and getVariable calls will continue to work without modification.

Creating a message context is also the preferred option if you are creating a new API for the DataPower API Gateway because it most closely aligns the API context with the way that various native DataPower API Gateway policies process it.

XSLT examples

To delete a header:

<apigw:clear-header message="'message'" name="'X-My-Header'"/>

To read a header:

<xsl:variable name="reqType" select="apigw:get-header('request', 'Content-Type')"/>
<xsl:variable name="currType" select="apigw:get-header('message', 'Content-Type')"/>

To set a header:

<apigw:set-header name="'Content-Type'" value="'text/xml'"/>

To get all headers:

<xsl:variable name="allReqHdrs" select="apigw:all-headers("'request'")"/>
<xsl:variable name="allCurrHdrs" select="apigw:all-headers("'message'")"/>

Manipulating the message status - examples

Accessing the message body - examples

Rejecting the session - examples