webMethods API Gateway tutorial
Author: Chandrasekaran, Vallab (vac@softwareag.com)
Supported Versions: 9.12, 10.0 & 10.1
Overview of the tutorial
API Gateway ships with a number of mediation policies that are enough to accomplish most of the use cases in the API management world. But in some cases the API Provider wants to do some custom operation apart from the out of the box policy support. API Gateway helps to accomplish this by letting the Provider create a custom logic using IS services and configure them using the Invoke webmethods IS policy for an API. Among the many use cases, one important and demanding use case would be to read and transform the contents of a request or response in a webMethods IS service to implement the custom logic. In this tutorial, we shall see how to read and transform the contents from a request or response, such as headers, query parameters, path parameters, HTTP method, payload, status code, status message, etc using Invoke webMethods IS policy in API Gateway.
Required knowledge
The reader is expected to:
- have a basic understanding of API Gateway and policy enforcement
- have knowledge on Software AG Designer to create and modify services
Why?
API Gateway forwards the incoming requests from the client to the native service, and forwards the response from the native service back to the client. Now when the API Provider wants to read the contents of the request and/or response to do some audit logging, or trigger a notification based on the contents of the request, the Provider can configure the Invoke webMethods IS policy to read the contents of the request/response using IS Service. In another case, if the API Provider wants to modify the request before forwarding the request to Native service as the native service wants to identify all incoming requests from API Gateway. In such case the Provider can configure the Invoke webMethods IS policy to add a header to all requests before they get routed to the native service.
Prerequisite steps
- Install advanced edition of API Gateway 10.1 or below
- Install the attached IS package 101EsbServices.zip, which is used as the sample in this tutorial
Details
Use cases
The following sections explain the use cases of Invoke webmethods IS policy in detail.
Use case 1: Transformation of request contents
The Invoke webMethods IS policy can be used to modify the contents of an incoming request such as headers, payload, query parameters, path parameters, HTTP method, payload using an IS Service.
The below diagram represents the flow of Invoke webMethods IS policy usage for transforming the request contents.
Design time flow
- API Provider creates an IS Service in Integration Server (in which API Gateway is running). The provider configures the IS Service to transform the request contents as per their need
- The API Provider configures the Invoke webMethods IS policy in Request processing stage of API Gateway, with the IS Service created in previous step
Run time flow
- The Client sends the request to API Gateway
- API Gateway invokes the webMethods IS Service configured by the API Provider. The IS Service transforms the request contents as defined by the API Provider
- API Gateway sends the transformed request to the native service
- Native server processes the transformed request and sends the response to API Gateway
- API Gateway forwards the response to client
Use case 2: Transformation of response contents
The Invoke webMethods IS policy can be used to modify the contents of an outgoing response such as headers, payload, status code, status message using an IS Service. The below diagram represents the flow of Invoke webMethods IS policy usage for transforming the response contents
Design time flow
- API Provider creates an IS Service in Integration Server (in which API Gateway is running). The provider configures the IS Service to transform the response contents as per their need
- The API Provider configures the Invoke webMethods IS policy in Response processing stage of API Gateway, with the IS Service created in previous step
Run time flow
- The Client sends the request to API Gateway
- API Gateway forwards the request to native service
- Native service processes the request and sends response to API Gateway
- API Gateway invokes the webMethods IS Service configured by the API Provider. The IS Service transforms the response contents as defined by the API Provider
- API Gateway sends the transformed response to the client
Other use cases
Apart from transformation of request and response contents, some other user cases of Invoke webMethods IS policy are listed below.
- Invoke webMethods IS Service can be used to route a request to a dynamically generated native endpoint. The IS service can be used by providers to identify the routing endpoint dynamically at runtime, and set the dynamic endpoint in message context. If Dynamic Routing policy is configured in API Gateway, then API Gateway reads the dynamic endpoint set by the IS Service from message context and routes the request to the dynamic endpoint. For more details about this, refer Dynamic Routing in API Gateway
- Logging the content of the request or response to a database or file, which can be used for audit at a later point
- Triggering a notification based on the content
Accessing client certificate used for SSL Connectivity
For accessing the client certificate used for SSL Connectivity, you can use the IS Service "esb.ssl:traceCertificates" in the attached 101EsbServices.zip IS package. Use the code in the getTransportCertificates() method in the above IS Service, to get the client certificates used for SSL Connectivity.
Accessing application information after Identification of Application
You can access inforamation of application after application identification using the below code in your IS service
public static final void myService(IData pipeline) {
IDataCursor idc = pipeline.getCursor();
Object object = IDataUtil.get(idc, PGConstants.MESSAGE_CONTEXT);
MessageContext synCtx = (MessageContext)object;
Application identifiedApp=(Application) synCtx.getProperty("gateway.identifiedApplication");
System.out.println("appId = " + identifiedApp.getApplicationID());
System.out.println("appName = " + identifiedApp.getName());
}
Transformation in action
The below section explains the usage of the sample IS services to use in Invoke webmethods IS policy to achieve the transformation use cases.
Inputs and outputs of IS service
In 10.1 and older versions of API Gateway, when you configure the Invoke webMethods IS policy in an API, API Gateway sends the below input values to the IS Service.
- MessageContext
- proxy.name
- EnvelopeString
- SOAPEnvelope
API Gateway accepts the below values from the IS Service output.
- MessageContext
- EnvelopeString
- UpdatedSoapRequest
The input and output pipeline variables of an IS Service in 10.1 and older versions is shown below.
Sample services usage
Please use the attached sample package (101EsbServices.zip) and follow the instructions in the below sections for the usage.
SOAP Request Processing Stage (Header/Payload Transformation)
- To read/transform headers in a SOAP request, you can use the IS Service “esb.soapRequestProcessing:transformHeaders”
- To read/transform payload of a SOAP request, you can use the IS Service “esb.soapRequestProcessing:transformPayload”
SOAP Response Processing Stage (Header/Payload Transformation)
- To read/transform headers in a SOAP response, you can use the IS Service “esb.soapResponseProcessing:transformHeaders”
- To read/transform payload of a SOAP response, you can use the IS Service “esb.soapResponseProcessing:transformPayload”
REST Request Processing Stage (Header/Payload/Query/Path/HTTP method Transformation)
- To read/transform headers in a REST request, you can use the IS Service “esb.restRequestProcessing:transformHeaders”
- To read/transform payload of a REST request, you can use the IS Service “esb.restRequestProcessing:transformPayload”
- To read/transform the query parameters of a REST request, you can use the IS Service “esb.restRequestProcessing:transformQuery”
- To read/transform the resource path of a REST request, you can use the IS Service “esb.restRequestProcessing:transformPath”
- To read/transform the HTTP method of a REST request, you can use the IS Service “esb.restRequestProcessing:transformHttpMethod”
REST Response Processing Stage (Header/Payload Transformation)
To read/transform headers in a REST response, you can use the IS Service “esb.restResponseProcessing:transformHeaders”
To read/transform payload of a REST response, you can use the IS Service “esb.restResponseProcessing:transformPayload”
Build path changes for using the code sample
If you are using the code sample from given package, add the below jars in the build path for the package in Software AG Designer.
- axis2-kernel-*.jar, axis2-transport-http-*.jar and synapse-core-*.jar from <Install_Location>\WS-Stack\lib
- <Install_Location>\IntegrationServer\instances\default\packages\WmAPIGateway\code\jars\apigateway-runtime.jar
- <Install_Location>\IntegrationServer\instances\default\packages\WmAPIGateway\code\jars\static\apigateway-api.jar
The above changes are to resolve the compile time errors thrown by Designer during edit and save of the java services inside the package. Also, make sure wmAPIGateway package is added as the package dependency to this package.
Limitations
- You cannot change the Content-Type for both SOAP and REST services using “esb.soapRequestProcessing:transformHeaders”. But you can change the Content-Type from version 10.2. For more details, refer section: Approach 1 - Transform the contents using pipeline parameters in Usage of “Invoke webMethods IS” policy - 10.2 and later versions
- For Method Type transformation to work using the code given in “esb.restRequestProcessing:transformHttpMethod”, both the original method and transformed method should be configured in the Resource and Methods section in API Gateway. From 10.2, when method transformation is done using pipeline variable "httpMethod", you need not configure the transformed method in API Gateway. For more details, refer section: Approach 1 - Transform the contents using pipeline parameters in Usage of “Invoke webMethods IS” policy - 10.2 and later versions
References
- For developing IS services using designer please refer https://documentation.softwareag.com/webmethods/wmsuites/wmsuite10-2/Designer/10-2_Service_Development_Help.pdf
Downloadable artifacts
- IS Sample services pacakge 101EsbServices.zip
Learn more
- For details about Dynamic Routing, refer Dynamic Routing in API Gateway
- For details on usage of Invoke webMethods IS policy in versions 10.2 and above, refer Invoke webMethods IS policy in API Gateway 10.2
- For details on using transformation policies to transform request and response contents refer Request and Response Transformation policies in API Gateway