APIs to manage messages

The context object for the API gateway supports the following APIs to mange messages.

To create a message object that represents a request or response, use the context.createMessage() API.

To retrieve the value of a specific message object, use the context.getMessage() API.

The context object for the API gateway supports the following APIs.

context.clear()

Deletes a variable in the API context.

Syntax
context.clear(name)
Parameters
Parameter Type Description
name String The variable name. The variable cannot be ready only. When the variable is an API property, this parameter indicates the property name.
Guidelines
The context.clear() API deletes a variable.
The format of the name parameter depends on whether the variable is for an API property.
  • When the variable is not an API property, such as the api.endpoint.address variable, the name format can be api.endpoint.address or api.endpoint.["address"].
    • context.clear('api.endpoint.address')
    • context.clear('api.endpoint.["address"]')
  • When the variable is an API property, the name format can be specified by one of the following methods, where the propertyName indicates the property name.
    • context.clear('propertyName')
    • context.clear('api.properties.propertyName')

context.createMessage()

Creates a message object that represents a request or response.

Syntax
context.createMessage(name,[message])
Parameters
Parameter Type Description
name String The name of a variable in the API context. The variable cannot be any read-only variables in the API context. See Variables in the API context.
message message object The message object to initialize the attributes of the object.
Guidelines
Creates a message object that represents a request or response. You can manipulate the header, payload, reason phrase, or status code. You can use the message parameter to assign values to the header or payload. If the message parameter is not specified, the created message is empty.
Example
In the GatewayScript, call the context.createMessage('foo') API to create the foo message and save the original request.
// Save the original request to another context variable, foo.
var foo = context.createMessage('foo');
var req_hdr = context.request.headers;
for (var h in req_hdr) {
  foo.header.set(h, req_hdr[h]);
}
context.request.body.readAsBuffer(function(error, buf) {
  if (error) {
    console.error('readAsBuffer error: '+error);
    throw error;
  } else {
    foo.body.write(buf);
  }
});

context.getAPIProperty()

Retrieves the value of the specified API property.

Syntax
context.getAPIProperty(propertyName)
Parameters
Parameter Type Description
propertyName String The name of an API property.
Guidelines
Retrieves the value of the specified API property. It returns undefined if the API property does not exist.

You can also use context.get() API to retrieve the value of the specified API property.

Example
Retrieve the value of the test API property.
context.getAPIProperty('api.properties.test') or ??? context.getAPIProperty('test')

context.get()

Retrieves the value of a variable in the API context.

Syntax
context.get(name)
Parameters
Parameter Type Description
name String The variable name. When the variable is an API property, this parameter indicates the property name.
Guidelines
Retrieves the value of the variable in the API context. This API returns undefined when the variable does not exist.
The format of the name parameter depends on whether the variable is for an API property.
  • When the variable is not an API property, such as the request.headers context, the format of the name parameter can be request.headers.headername or request.headers["headername"].
    • context.get('request.headers.Content-Type')
    • context.get('request.headers["Content-Type"]')
  • When the variable is an API property, the format of the name parameter can be specified by one of the following ways, where the propertyName indicates the property name. The short propertyName format applies only when the current action in the assembly does not have a property with the same name.
    • context.get('propertyName')
    • context.get('api.properties.propertyName')
    You can specify the local variable with the title and function-name parameters to retrieve the instantiated assembly function parameter values and the name of the assembly function from the context of the current message. The following example shows the format of the returned data.
    { 'title': 'Title of function call assembly action',
       parameter:
         { 'name_1': 'value_1',
           'name_2': 'value_2',
           'name_3': 'value_3' },
       'function-name': 'assembly-function-name'
    }
Examples
  • Retrieve the value of the Content-Type variable in the request.headers context.
    context.get('request.headers["Content-Type"]')
  • Retrieve the value of the test API property.
    context.get('api.properties.test')
  • Retrieve the value of the title property for the assembly function that is being processed.
    context.get('local.title')
  • Retrieve the value of the function-name property to retrieve the name of the assembly function.
    context.get('local.function-name')

context.getMessage()

Retrieves the value of a message object.

Syntax
context.getMessage(varName)
Parameters
Parameter Type Description
varName String The name of a variable in the API context. The variable represents the message object to retrieve.
Guidelines
Retrieves the value of a message object and creates another message object in which you can manipulate the header, payload, reason phrase, or status code.
Example
Store the output of the invoke assembly action in the "foo" named variable in the API context, which represents the response. Call the context.getMessage('foo') API in a GatewayScript assembly action to retrieve the response and manipulate its header and payload.
var foo = context.getMessage('foo');
var foo_hdrs = foo.header.get();
foo.body.readAsBuffer(function(error, buf) {
  if (error) {
    console.error('readAsBuffer error: '+error);
    throw error;
  } else {
    context.set('tmp.var', buf);
  }
});

context.getType()

Retrieves the type of the variable.

Syntax
context.getType(name)
Parameters
Parameter Type Description
name String The name of the variable.
Guidelines
Retrieves the type of the variable. It returns undefined if the variable does not exist.
Examples
  • Retrieve the type of the request.headers["Content-Type"] variable.
    context.getType('request.headers["Content-Type"]')
  • Retrieve the type of the test API property.
    context.getType('api.properties.test')

context.isJSON()

Checks whether the value represents a JSON media type.

Syntax
context.isJSON(contentType)
Parameters
Parameter Type Description
contentType String The value to check.
Guidelines
Checks whether the value represents a JSON media type. It returns true if the value is a JSON media type. Otherwise, it returns false.
Example
Check whether the value of the Content-Type header in a request is a JSON media type.
var contentType = context.request.header.get('Content-Type');
if (context.isJSON(contentType)) {
  ...
}

context.isXML()

Checks whether the value represents an XML media type.

Syntax
context.isXML(contentType)
Parameters
Parameter Type Description
contentType String The value to check.
Guidelines
Checks whether the value represents an XML media type. It returns true if the value is an XML media type. Otherwise, it returns false.
Example
Check whether the value of the Content-Type header in a request is an XML media type.
var contentType = context.request.header.get('Content-Type');
if (context.isXML(contentType)) {
  ...
}

context.list()

Lists the first level of properties in the API context.

Syntax
context.list()
Guidelines
Lists the first level of properties in the API context.
Example
List the first level of properties in the myAPI context.
context.list()
The return is as follows.
{ 
  "foo": "object",
  "bar": "string",
  "baz": "number", 
  "request": "message", 
  "message": "message"
}

context.reject()

Causes the assembly rule to be in error after processes the GatewayScript when the script does not stop immediately.

Syntax
context.reject(errorName[,errorMessage])
Parameters
Parameter Type Description
errorName String The name of the error.
errorMessage String The custom error message for the returned fault, which can include troubleshooting information.
Guidelines
Raises a custom error. The API gateway returns an error message when the API responds to the client. After the context.reject() call, the script does not stop but continues to run until the current GatewayScript action completes. After the GatewayScript action completes, the current assembly rule is ended.
When the context.reject() API raises an error, by default, the "500 Internal Error" status code is returned. If you want to overwrite the default status code, you must reconfigure the context.message.statusCode property after the context.reject() API call. For example, the following codes indicate that the "501 Custom Error" custom status code is returned.
context.reject("GWSError","message");
context.message.statusCode = "501 Custom Error";
Example
Raise a custom MyError error to the assembly rule.
context.reject('MyError', 'Some error message')

context.request.body.readAsBuffer()

Reads the original payload of the request in binary and returns the contents as a Buffer object.

Syntax
context.request.body.readAsBuffer(function(errorObject,bufferObject){})
Parameters
Parameter Type Description
errorObject error object The error object that contains the error information if any error occurs during processing. In the asynchronous callback, check the error before you use the contents of the bufferObject to ensure that no error occurred.
bufferObject Buffer object The Buffer that contains the returned content of the specified context in binary.
Guidelines
Reads the original payload of the request in binary type from the request.body variable and returns the content as a Buffer object. If the content is not a Buffer object, an error object is returned. If the data is empty, the returned data is undefined.
Examples
context.request.body.readAsBuffer(function(error, buf)
  {
    if (error) {
      console.error('readAsBuffer error: '+error);
    }
    else {
      context.set('tmp.var', buf);
    }
  }
)

context.request.body.readAsBuffers()

Reads the original payload of the request in binary and returns the contents as a Buffers object.

Syntax
context.request.body.readAsBuffer(function(errorObject,buffersObject){})
Parameters
Parameter Type Description
errorObject error object The error object that contains the error information if any error occurs during processing. In the asynchronous callback, check the error before you use the contents of the buffersObject to ensure that no error occurred.
bufferObject Buffers object The Buffers object that contains the returned content of the specified context in binary.
Guidelines
Reads the original payload of the request in binary type from the request.body variable and returns the content as a Buffers object. If the content is not a Buffers object, an error object is returned. If the data is empty, the returned data is undefined.
Examples
context.request.body.readAsBuffers(function(error, bufs)
  {
    if (error) {
      console.error('readAsBuffers error: '+error);
    }
    else {
      context.set('tmp.var', bufs);
    }
  }
)

context.request.body.readAsJSON()

Reads the original payload of the request in a JSON representation and returns the contents as a JSON object.

Syntax
context.request.body.readAsJSON(function(errorObject,jsonObject){})
Parameters
Parameter Type Description
errorObject error object. The error object that contains the error information if any error occurs during processing. In the asynchronous callback, check the error before you use the contents of the jsonObject to ensure that no error occurred.
jsonObject JSON document. The JSON document that contains the returned content of the specified context in a JSON representation.
Guidelines
Reads the original payload of the request in a JSON representation from the message.body variable and returns the contents as a JSON object. If the content is not a JSON document, an error object is returned. If the data is empty, the returned data is undefined.
Examples
context.request.body.readAsAsJSON(function(error, json)
  {
    if (error) {
      console.error('readAsJSON error: '+error);
    }
    else {
      context.set('tmp.var', json);
    }
  }
)

context.request.body.readAsXML()

Reads the original payload of the request in XML type and returns the contents as a NodeList object.

Syntax
context.request.body.readAsXML(function(errorObject,nodeList){})
Parameters
Parameter Type Description
errorObject error object The error object that contains the error information if any error occurs during processing. In the asynchronous callback, check the error before you use the contents of the returned nodeList to ensure that no error occurred.
nodeList NodeList object The NodeList object that contains the returned content of the specified context as XML nodes if no error occurs.
Guidelines
Reads the original payload of the request in XML type from the message.body variable and returns the contents as a NodeList object. The resultant NodeList is accessed with methods of the DOM API, XML, and other modules, as provided by GatewayScript. The NodeList object can contain zero or more nodes. If the content is not an XML node, an error object is returned. If the data is empty, the returned data is undefined.
Examples
context.request.body.readAsAsXML(function(error, xml)
  {
    if (error) {
      console.error('readAsXML error: '+error);
    } 
    else {
      context.set('tmp.var', xml);
    }
  }
)

context.request.header.get()

Retrieves the value of the original named header of the HTTP request.

Syntax
context.request.header.get([headerName])
Parameters
Parameter Type Description
headerName String The name of the original header of the HTTP request.
Guidelines
Retrieves the value of the original named header of the HTTP request. By default, it retrieves all request headers.
Example

context.request.headers

Retrieves values of all request headers.

Syntax
context.request.headers
Guidelines
Retrieves values of all request headers.
Example

context.set()

Sets or adds a variable in the API context.

Syntax
context.set(name,value)
Parameters
Parameter Type Description
name String The variable name. The variable cannot be read-only. When the variable is an API property, this parameter indicates the property name.
value String The value to set for the variable.
Guidelines
Sets or adds a variable in the API context. The following rules apply.
  • When the specified variable does not exist, creates a variable with assigned value.
  • When the specified variable exists and is not read-only, the assigned value overrides the existing value.

When you set the value for the message.status.code variable, the value must be three-digit value in the range 100 - 999.

You cannot use this API to set the error.message variable to stop the current assembly rule. To stop the assembly rule, call the context.reject() API.

The format of the name parameter depends on whether the variable is for an API property.
  • When not an API property, such as message.status.code, the API is context.set('message.status.code','555')
  • When the variable is an API property, the format of the name parameter can be specified by one of the following ways, where the propertyName indicates the property name.
    • context.set('propertyName','test')
    • context.set('api.properties.propertyName','test')

When you use this API, the variable is stored in the context as a JSON object. For a JSON object, six types exist - object, array, string, number, boolean, and null. Any value beyond these types might be implicitly converted during the context.set() call. The only exception is xxx.body, where you can save the entire document as a BLOB, an XML document, or a JSON document; for example, request.body or message.body.

Example
  • Add a header that is named message.headers.test.
    context.set('message.headers.test','teststring')
  • Override the value of the existing message.headers.test variable.
    context.set('message.headers.test',2245)

context.swagger.readAsJSON()

Reads the OpenAPI document of the configuration of the API definition.

Syntax
context.swagger.readAsJSON(function(errorObject,jsonObject){})
Parameters
Parameter Type Description
errorObject error object. The error object that contains error information if any error occurs during processing. In the asynchronous callback, check the error before you use the contents of the jsonObject to ensure that no error occurred.
jsonObject JSON document. The OpenAPI document to return in JSON format.
Guidelines
Reads the OpenAPI document that is populated in the configuration of the API definition of the current API request and returns the document in JSON format. If the OpenAPI document does not exist or is not JSON formatted, an error is returned.