GatewayScript code examples
Example GatewayScript code snippets to help the creation of a gatewayscript policy.
- The GatewayScript functions that are listed here use the default common name
apim
to call the methods. You can change the common name to one of your choice by using the functionvar name = require('./apim.custom.js');
; for example, setting
would set the calls to start with the common namevar apic = require('./apim.custom.js');
apic
. However, the use ofrequire()
adds latency. - If you are using GatewayScript within a user-defined policy, there are additional configuration requirements to those listed here. For example, the output from a user-defined policy must be an XML node-set or a JSONx message. For information about how to create an implementation for a user-defined policy, see Implementing your policy, and for example GatewayScript code snippets, see Implementation code examples.
Access the assembly context
The following code snippets show examples of how to access the assembly context. The examples use the default common name ofapim
.Example one returns the request
context:
apim.getvariable('request');
foo
:apim.getvariable('request.headers.foo');
apim.setvariable('message.headers.name', value, action)
where - name is the name of the message header that you want to set, add, or clear.
- 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, you would specify the value as
request.headers.content-type
. This property is only required whenset
oradd
is specified as the action. - action is the action that you want to apply to the variable. Valid options are:
set
add
clear
set
is applied.
For a complete list of context variables, see API Gateway context variables, and for more information about how to reference context variables in IBM® API Connect see Variable references in API Connect.
Read input synchronously
The following code snippets show examples of how to read input synchronously by using theapim.getvariable
function to read data direct from a context. JSON input is returned as a JavaScript object. XML data is returned as a NodeList object (DOM).Example one returns a synchronous read of the original request body into the variable that is called json:
var json = apim.getvariable('request.body');
var xml = apim.getvariable('message.body');
Read input asynchronously
The following code snippets show theapim.readInput()
calls that you can use to perform a JavaScript callback function to read input data asynchronously into a variable. JSON input is returned as a JavaScript object. XML data is returned as a NodeList object (DOM). Other types of input are returned as a Buffer object.apim.readInput(callback(err,input) {});
apim.readInputAsJSON(callback(err,json) {});
apim.readInputAsXML(callback(err,nodelist) {});
apim.readInputAsBuffer(callback(err,buffer) {});
apim.readInput()
function attempts to determine the input data type and call the
appropriate apim.readInputAstype()
function in order to return
the data in the correct format. However, to ensure that the correct data type is returned, use the
apim.readInputAstype()
function.The
apim.readInputAstype()
function reads the data from either the
INPUT context (for example session.INPUT
), or from a policy output context (for
example policy.output
), depending on whether a previous policy had been called that
had written output to a policy output context. This function then calls the underlying IBM
DataPower® GatewayScript
readAstype
method on the relevant context to read the data, and then use JavaScript callbacks to return the data to a variable. For more information about DataPower methods, see APIs for methods.
apim.readInputAsJSON()
callback function to get data into a variable that
is called
json:apim.readInputAsJSON(function (error, json) {
if (error)
{
// handle error
}
else
{
// the json parameter will contain the json data that has been read
// process the json object in some way and write to the output context
if (json.test=='true')
{
// if json data contains a variable called test that is set to true, then also add some test data
json.data = 'This is my test data'
}
session.output.write(json);
// write to the output context
}
});
Configure error information
The following code block shows an example of how to configure the policy implementation to produce error information by using theapim.error()
function. In this example, MyError
is thrown to
the assembly flow. If there is a catch handler it catches this error, otherwise the assembly skips
the execution of the flow and sends a 500 Internal Error
response.apim.error('MyError', 500, 'Internal Error', 'Some error message');
where:MyError
is the name of the error.500
is the HTTP code of the required error message.Internal Error
is the HTTP reason phrase for the error.Some error message
is the suggested action for the user.
(From API Connect version 5.0.8.8 onward) Accessing the caught exception in a catch block
catch
block of an API assembly, you can
obtain the details of the current caught exception. A possible use would be to create a custom error
response using the details of the caught
exception.let exception = apim.getError();
The function returns a JSON object;
for
example:{
"name": "OperationError",
"message": "This is a thrown Operation Error",
"policyTitle": "Throw Operation Error",
"status": {
"code": "500",
"reason": "Internal Server Error"
}
}
Write output
'{ "status": "created" }'
, by using the session.output.write
variable:session.output.write('{ "status": "created" }');
The
session.output.write
variable is a standard GatewayScript method that writes data
to the output context. For more information, see Contexts and sessions.session.output
variable:apim.output('application/type');
For example, if
you were creating a policy that
called:session.output.write('<test>this is some xml data</test>');
the
policy would write XML data to the output context. You would need to configure the policy to also
callapim.output('application/xml');
to tell the system that the output is XML.
It can cause issues in the processing of the policy if the actual output context format, and the
format that is specified in apim.output
, are different.apim.setvariable
to manipulate message.body
and you use apim.output
to set the output type, you must call apim.setvariable
before
apim.output
.