Author: Narayanan, Lakshmanan
Supported Versions: 9.12 & above
Introduction
API Gateway is capable of processing error message differently for different conditions.
Note: Error Processing in API Gateway means, based on a set of conditions construct or transform an error message that is to be sent to the client or allow the Native provider Fault response to be sent back as is.
API Gateway can construct error messages from predefined templates or transform the Native error with the help of XSLT Transformations or webMethods ESB services.
The illustration explains the flow detail.
Error Conditions
API Gateway can respond differently for different error conditions. An error condition can be:
- Status Code: This denotes the Status code with which the Native service replies. This should be a value between 4xx and 5xx.
- HTTP Header: This denotes any HTTP Header that the Native service has added to the response. The provider configures the name of the header and its value. This is an exact match to the header value.
- XPath Expression: The XPath Expression for the Native service response.The provider configures the XPath and namespaces and the Value that this XPath should match.
XPath for JSON
For REST services returning JSON responses, XPATH can be defined in two ways.
Let's consider a JSON response from the Native provider
{
"author" : {
"name" : "JK Rowling"
.............
}
}
The XPath for the name can be
//name="JK Rowling" (or) //authors/name="JK Rowling"
Note: Error Conditions within a policy follow the 'AND' operator and between policies follow the 'OR' operator.
Pre-processing Steps
Pre-processing refers to processing of native service error response in API Gateway.
There might be cases like:
- Log exact error message sent by Native Service without any changes
- Remove any critical information sent in response by Native Service but not be logged by API Gateway or shared to client.
This can be a XSLT Transformation file or a webMethods ESB service configured in this API Gateway instance.The service provider can configure multiple XSLT Transformations and webMethods ESB services and the order is exactly preserved at runtime.
If the webMethods IS Service does not exist on the Integration Server that hosts API Gateway, then the user cannot add the webMethods IS service to the API. Also, an error thrown by the ESB service stops processing other condition error processing policy and sends the native service error response.
A sample configuration is shown below.
The order of execution for the pre-processing steps is:
- Execute mycompany:execute webMethods IS Service
- Execute mycompany:log webMethods IS Service
- Exceute mycompany:logAgain webMethods IS Service
- Transform native Error message using AnotherTransformation.xsl
XSLT Transformation Condition
XSLT transformation happens on the native service error message. Also the XSLT transformation happens only if native service sends the error message with Content-type as application/xml or application/json
Error Messages
API Gateway allows the provider to configure Templates that are sent to the client. These templates can be of XML or JSON or Text Type.
API Gateway at runtime decides what template to choose depending on the Accept header that the Client sends. The provider can configure a default error message that API Gateway needs to send if an Accept header is not received from the client.
XML Message Type:
Denotes an XML Template and for requests with Accept: application/xml
JSON Message Type:
Denotes an JSON Template and for requests with Accept: application/json
Note that API Gateway DOES NOT validate the correctness of the XML and JSON error messages that are configured in the policy.
Text Message Type:
The Text Message type denotes what should be wrapped inside the 'Exception' element.
Example:
For an Accept Content type 'application/json' and <TEXT-MESSAGE THAT IS CONFIGURED> is the text message that is configured.
{
"Exception" : <TEXT-MESSAGE THAT IS CONFIGURED>
}
For an Accept Content type 'application/xml'
<Exception> <TEXT-MESSAGE THAT IS CONFIGURED> </Exception>
This can be either configured at policy level or Global level (Administration -> General -> service fault)
Consider the following snapshot with appropriate values configured in the policy at API Gateway.
For the above configuration,
Note the templates being replaced in the table
| Accept | Response Error Messag |
| application/json | { "error" : "Service encounted an Error. at Time 12:50:33, 23/04/2015" } |
| application/xml | <error> Service encountered an Error. at Time 12:50:33, 23/04/2015 for consumer MyConsumerApplication </error> |
 |
Note that 'application/json' is always the default when the Accept header is not present. Also, since the Text { |
There are several combinations of the above Error message configurations out of which some are discussed in the cheat sheet below.
Failure Message Cheat Sheet
Assume that error is thrown from Native service and Send Native provider Fault is not configured.
| SNO | XML Message Type configured |
JSON Message Type configured |
Text Message Type configured |
Default | Accept Header from client | Response |
| 1 |  |
|
|
XML | application/xml | XML Template with values replaced. |
| 2 | |
|
|
XML | application/json | JSON Template with values replaced. |
| 3 | |
|
|
XML | Something other than application/xml and application/json |
XML Template with values replaced. |
| 4 | |
|
|
XML |  |
XML Template with values replaced. |
| 5 | |
|
|
JSON | application/xml | XML Template with values replaced. |
| 6 | |
|
|
JSON | application/json | JSON Template with values replaced. |
| 7 | |
|
|
JSON | Something other than application/xml and application/json |
JSON Template with values replaced. |
| 8 | |
|
|
JSON | |
JSON Template with values replaced. |
| 9 | |
|
|
Text | application/xml | XML Template with values replaced. |
| 10 | |
|
|
Text | application/json | JSON Template with values replaced. |
| 11 | |
|
|
Text | Something other than application/xml and application/json say X |
Default message that is configured with values replaced in the content type X |
| 12 | |
|
|
Text | |
Default message that is configured with values replaced in application/json. |
| 13 | |
|
|
|
|
API Gateway generated error in application/json. Usually will be of the form "{ "Exception" : "API-Gateway encountered an Error...."} |
| 14 | |
|
|
Text | application/xml | Default message that is configured with values replaced in application/xml |
| 15 | |
|
|
Text | application/json | Default message that is configured with values replaced in application/json |
| 16 | |
|
|
Text | |
Default message that is configured with values replaced in application/json |
| 17 | |
|
|
JSON | application/xml | API Gateway generated error in application/xml. Usually will be of the form <Exception>API-Gateway encountered an Error</Exception> |
| 18 | |
|
|
JSON | |
JSON Template with values replaced. |
| 19 | |
|
|
|
application/xml | API Gateway generated error in application/xml. Usually is of the form <Exception>API-Gateway encountered an Error</Exception> |
| 20 | |
|
|
|
application/json | API Gateway generated error in application/xml. Usually is of the form <Exception>API-Gateway encountered an Error</Exception> |
| 21 | |
|
|
|
|
API Gateway generated error in application/xml. Usually is of the form <Exception>API-Gateway encountered an Error</Exception> |
If Send Native provider error is configured either at the service level or at the Global configuration page then even if any of the Failure messages are configured they are not taken into account and neglected.
Custom Error Variables
| No | Variable Name | What it does |
| 1 | $ERROR_MESSAGE | This can be any error including errors generated by API Gateway for policy violations. |
| 2 | $OPERATION | Operation that is invoked. |
| 3 | $SERVICE | Service that is invoked. |
| 4 | $TIME | Time of invocation. |
| 5 | $DATE | Date of invocation |
| 6 | $CLIENT_IP | The client IP Address that is invoked |
| 7 | $USER | The IS User |
| 8 | $CONSUMER_APPLICATION | The API Gateway Consumer Application |
| 9 | $NATIVE_STATUS_CODE | The HTTP Error status code that is returned by the Native service. |
The service provider can go ahead and configure custom error variables using XPATH of either request or the response. These custom error variables and predefined variables are available for pre-processing and post-processing webMethods IS services.
The example below explains how to add custom error variable
Post-processing Steps
The post-processing of error messages is done after API Gateway has processed the error message.
This can be a XSLT Transformation file or a webMethods ESB service configured in this API Gateway instance.The service provider can configure multiple XSLT Transformations and webMethods ESB services and the order is exactly preserved at runtime.
If the webMethods IS Service does not exist on the Integration Server that hosts API Gateway, then the user cannot add the webMethods IS service to API.
Also an error thrown by the ESB service stops processing other condition error processing policy and sends the native service error response.
Sending Native provider Fault message:
This option enables to send the 'Native provider fault' back to the client without API Gateway changing them. If this is enabled only the Pre, Post processing steps are executed and the Native provider error is sent as is to the client.
This can either be configured at the global level at the Service Fault page in API Gateway or at the Policy level.
Deploying Sample
The Sample has a native service and an API Gateway API to handle Conditional Error Processing. Conditional Error Processing handles HTTP Status code 500 and 404. It also have webMthods IS service to demonstrate the invocation of it and handling custom error variable. Follow these steps to deploy the sample.
- Download the three zip files.
- Import Employee management.zip to IS Server where the wmapigateway instance is running.
- import mycompany.zip to IS server and add the compiled library for mycompany package. Add all the jars inside WmAPIGateway package and WS-stack\lib to this package. Then add WmAPIGateway package as a runtime dependency for this package.
- Import Employee REST Service CEP.zip to API Gateway and activate the service.
Note: Edit the native service host to map the employee management deployed host