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.
- APIs to access and manipulate variables in the API context.
- APIs to read the original payload and return the content in a specific format.
- APIs to retrieve values of the original header of a request.
- APIs to manipulate properties of the current message.
- API to raise a custom error and stop the processing of the current assembly rule.
- APIs to check the media type of the
Content-Type
header in a message. - API to read the OpenAPI document in the configuration of the API definition.
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 beapi.endpoint.address
orapi.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')
- When the variable is not an API property, such as the
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 thefoo
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 berequest.headers.headername
orrequest.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 thelocal
variable with thetitle
andfunction-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' }
- When the variable is not an API property, such as the
- Examples
-
- Retrieve the value of the
Content-Type
variable in therequest.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')
- Retrieve the value of the
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 thecontext.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')
- Retrieve the type of the
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 returnsfalse
. - 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 returnsfalse
. - 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 thecontext.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 iscontext.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
, andnull
. Any value beyond these types might be implicitly converted during the context.set() call. The only exception isxxx.body
, where you can save the entire document as a BLOB, an XML document, or a JSON document; for example,request.body
ormessage.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)
- Add a header that is named
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.