webMethods API Gateway tutorial
Author: Chandrasekaran, Vallab (vac@softwareag.com)
Supported Versions: 9.12 and above
Overview of the tutorial
API Gateway enables enterprises to secure their APIs by providing service virtualization and mediates the requests to that API using policies and their enforcement. The configured mediation policies (security, transformation, routing, etc) are enforced for each request before they are forwarded to the the native service using routing policies. There are a number of routing policies supported in API Gateway like Straight through routing (default), Context based routing, Load balancer routing, etc. In this tutorial, we will discuss in detail about the Dynamic Routing policy which enables API Gateway to compute the native endpoint URL at the run-time based on the incoming request parameters or custom logic and then route the requests to that dynamically computed endpoint.
The tutorial covers the following steps in detail.
- Configuring Dynamic routing policy in API Gateway UI using the IS service "com.softwareag.mediator.samples.dynamicRouting.validateDynamicURI" available as part of the wmMediatorSamples Package
- Use case 1 - Using the HTTP header in the request
- Use case 2 - Using context variable value set by the IS Service
Required knowledge
The reader is expected to,
- have a basic understanding of API Gateway and policies
- have knowledge on Software AG Designer to create and modify services
Why?
API Gateway routes the incoming request to the native service endpoint URL which is configured in the routing policies under Routing stage. While other routing policies support the configuration of static URL, there was no provision to dynamically modify the URL at runtime based on some parameters or custom logic. Dynamic routing policy enables API Providers to configure routing policy in such a way that, the routing endpoint can be dynamically modified using the value of a HTTP Header in the request or an IS Service to write Java code to apply some custom logic to dynamically modify the routing endpoint. With this policy in place the Provider has a strong control over the routing mechanism.
Prerequisite steps
Complete the below prerequisites to make you ready to get into the details of the dynamic routing support in API Gateway.
- Install API Gateway advanced editions of version 9.12 or greater
- Install the attached IS package wmMediatorSamples.zip, which will be used as the sample service in this tutorial
Details
The following sections provide a detailed view of the use cases and samples for the dynamic routing.
Use cases
Lets start this section with an use case for each of the two approaches using which the Dynamic routing can be accomplished.
Use case 1: Using HTTP Header
In this case the native service endpoint is obtained from the pre-configured HTTP Header of the incoming request.
For example,
- The client calls Salesforce Login Service to authenticate, and the response from Salesforce contains a dynamic URL which is to be used for subsequent invocations to different services
- The client sends another request to an API Gateway API with a pre-defined header containing the dynamic URI from the Salesforce response
- API Gateway extracts this header to use as dynamic URI or compute the dynamic URI using the header as part of the URI and routes the request to it
Use case 2: Using webMethods IS Service
In this case the API Provider programmatically influences the routing decisions based on a custom logic.
For example:
- The client sends a request to API and the request is processed with mediation policies like IAM, etc
- The provider implements a custom logic using webMethods IS Service to compute the URI (eg. determine the URI dynamically based on the identified user, etc)
- Provider sets the dynamically computed URI to the Context Variable 'ROUTING_ENDPOINT' in the message-context
- API Gateway extracts this dynamic URI from context variable in message-context and routes the request to that URI
In the next sections, we will look at these use cases in detail.
Sample Package
Before get into the details, below are the list of services present in the attached IS package wmMediatorSamples, which we will use in our below use cases.
- com.softwareag.mediator.samples.dynamicRouting.validateDynamicURI:_get : This is a REST Service, which will be used as Native Service in our demo scenario
- com.softwareag.mediator.samples.dynamicRouting:getDynamicUri : This service is the login service, which will be used by client to get the dynamic URI. This dynamic URI is nothing but the authenticated username encoded
- com.softwareag.mediator.samples.dynamicRouting:setDynamicUriInContext : This webMethods IS Service is used to compute dynamic URI and set the URI in message context
Now lets see in action how these two approaches can be used by means of workflows and configuration in API Gateway UI.
Dynamic Routing Using HTTP Header
In the step lets see the usage of first use case - dynamic routing using HTTP header, in detail. The below workflow outline the steps needed to send the dynamic URI in a HTTP header.
Workflows
Design time
- Provider configures the API with Dynamic Routing using HTTP header
Runtime
- Client hits the (native) login service with login credentials
- The login service responds with a token generated based on the incoming client credentials
- The client then passes this token as a HTTP header to the API Gateway API (configured with Dynamic Routing)
- This header value is then used to compute the native service URL dynamically at runtime. API Gateway routes the incoming request to the dynamically computed URI
- The native service reads the token from the dynamic URI (from its path param), and validates against the login credentials in the request, and sends response
- API Gateway forwards the response to Client
Demo steps
Step 1: Configuring API with "validateDynamicURI" as native service
In this step we use the "com/softwareag/mediator/samples/dynamicRouting/validateDynamicURI" as the Native REST Service. You could choose to write your own native service.
In API Gateway, click on APIs → Create API → Create API from Scratch → REST. Provide name of the API as "DynamicRoutingDemoService". Click on "Technical Details" section and enter "HOSTNAME:5555" as Host and "/rest/com/softwareag/mediator/samples/dynamicRouting/" as Base Path.
Click on "Resources and Methods" section and click on "Add Resources". Enter Resource name and Resource Path as "/validateDynamicURI". Select "GET" in supported methods and click "add".
Step 2: Configuring policies in the API
Edit the "DynamicRoutingDemoService" API and click on Policies. Add "Dynamic Routing" policy under the Routing stage.
Configure Route To → Endpoint URI with value as, http://HOSTNAME:5555/rest/com/softwareag/mediator/samples/dynamicRouting/validateDynamicURI
Under Rule section,
- Select "Header" as Route Using.
- Enter a header-name (eg: dynHeader) in Header Name. This is the header name expected in the incoming request that invokes this API Gateway API.
- Configure Rule → Route To → Endpoint URI with value, "http://HOSTNAME:5555/rest/com/softwareag/mediator/samples/dynamicRouting/validateDynamicURI/${sys:dyn-Endpoint}". The system-defined alias "${sys:dyn-Endpoint}" is replaced at runtime with the Dynamic URI from the header in the incoming request. For Example, if the incoming request contains the configured header name "dynHeader" and header value "ABC", then it will be redirected to, http://HOSTNAME:5555/rest/com/softwareag/mediator/samples/dynamicRouting/validateDynamicURI/ABC
Add "Outbound Authentication Transport" policy from Routing stage and configure "Authentication scheme as "Basic" and Authenticate using "Incoming HTTP basic auth credentials".
Save and activate the API.
Step 3: Call the intermediary login service to get the Dynamic URI
The intermediary login service used in this step is "com.softwareag.mediator.samples.dynamicRouting:getDynamicUri" in the attached wmMediatorSamples package. You can create a custom IS service with custom logic to achieve this step. Note that, then you would need to modify the native service logic to reflect these changes as well.
- Go to your client (eg: SOAP UI) and create a new REST Project (name:LoginService) with the following URI, and import resources and methods. "http://HOSTNAME:5555/invoke/com.softwareag.mediator.samples.dynamicRouting:getDynamicUri"
- Open the "Request 1" in the Project, and provide an IS User (eg: Administrator) and its password in the Authorization Header.
- Add "application/json" as Accept Header for readability.
- Invoke the service. You could see a dynamic-URI "QWRtaW5pc3RyYXRvcg==" is generated based on the authenticated user. (If you try with different user, you would get a different token)
Step 4: Invoking the API with HTTP Header
Create a REST Project in SOAP UI with the Gateway endpoint "http://HOSTNAME:5555/gateway/DynRoutingDemoService/1.0/validateDynamicURI". Open the request from the GET method. Add the username/password (Eg: Administrator) in the Authorization Header.
Add the header configured for Dynamic Routing with the URI value acquired from the intermediary login service, in previous step (3.3). Eg: headerName = "dynHeader", headerValue = "QWRtaW5pc3RyYXRvcg==", as shown in image below. Also, add "application/json" as the Accept Header and invoke the request. You will see the response as below.
Failure scenarios
Scenario 1 - Invoke the request with invalid value in dynamic-header
Now modify the header value to some random value - say "xyzaBc" and invoke the request. You will get the following response
{
"response_code": "402",
"response_message": " Access Denied. Check if authentication provided is correct, and dynamic URL entered is correct!"
}
Scenario 2 - Invoke the request with correct value in dynamic header, but a different user in authorization header
Again reset the header value to original value "QWRtaW5pc3RyYXRvcg==". Modify the authorization header with credentials of another IS Admin User instead of Administrator. (say, user1) and invoke the request. You could see you get the same failure message in the response.
Follow the same steps in 3 to call the intermediary login service to get the Dynamic URI for the user "user1". In our case, we get the dynamic URI as "dXNlcjE=" for user1. Send the request after modifying the dynamic-header value to "dXNlcjE=" in the request. You will get successful response again, as shown below.
Dynamic Routing Using Context Variable set by webMethods IS Service
Now lets look at the steps to programmatically influence the routing decisions based on a custom logic in the IS service.
Workflows
Design time
- Provider creates a webMethod IS Service to authenticate the incoming user, and generate the dynamic URI based on a custom logic. This service sets the dynamic URI in the message context with key "ROUTING_ENDPOINT". (The webMethod IS Service used in our demo is com.softwareag.mediator.samples.dynamicRouting:setDynamicUriInContext)
- Provider configures the API Gateway API with Dynamic Routing using Context Variable, and configures the webMethod IS Service in the Request Processing
Runtime
- The client invokes the API Gateway API with credentials
- In Request Processing step, API Gateway calls the configured webMethod IS Service with incoming credentials
- The webMethod IS Service identifies user, generates the dynamic URI based on a custom logic, and sets it in the message context with key "ROUTING_ENDPOINT"
- API Gateway gets the URI from message context, and computes the dynamic URI and hits the Native Service using the URI
- The native service reads the token from the dynamic URI (from its path param), and validates against the login credentials in the request, to send response
- API Gateway forwards the response to Client
Demo steps
Step 1: Create a webMethods IS Service to generate dynamic URI using custom logic
In our demo sample, this step is already done in the webMethods IS Service named "com.softwareag.mediator.samples.dynamicRouting:setDynamicUriInContext". If you want to use different logic to compute the dynamic URI and set it in the message context, you can follow the steps below.
Compute Dynamic URI using custom logic - Create a webMethods IS Service using designer, to generate the dynamic URI using custom logic.
Set the computed Dynamic URI in Message Context - From this service, call the webMethods IS Service "com.softwareag.mediator.samples.dynamicRouting.utils:setDynamicContext" in the wmMediatorSamples package, with the computed dynamicURI as input parameter, as shown in the image below.
In the above image, "com.softwareag.mediator.samples.dynamicRouting:getDynamicUri" computes the dynamic URI from input credentials (the dynamic URI is the encoded username) and sets the dynamic URI using "setDynamicContext" IS service.
In the above image, "com.softwareag.mediator.samples.dynamicRouting.utils:setDynamicContext" IS Service sets the dynamic URI in the message context with Variable Name "ROUTING_ENDPOINT".
Step 2: Configuring API Gateway API with policies
We shall use the same "DynamicRoutingDemoService" API used for "Dynamic Routing using Headers". You can however choose to create a new API by following these steps. Edit the "DynamicRoutingDemoService" API and click on Policies. Add "Invoke webMethods IS" policy under Request processing stage, and configure the "com.softwareag.mediator.samples.dynamicRouting:setDynamicUriInContext" IS Service in the policy. Add "Dynamic Routing" policy under the Routing stage.
- Configure Route To → Endpoint URI with value as, http://HOSTNAME:5555/rest/com/softwareag/mediator/samples/dynamicRouting/validateDynamicURI
- Under Rule section,
- Select "Context" as Route Using
- Configure Rule → Route To → Endpoint URI with value, "http://HOSTNAME:5555/rest/com/softwareag/mediator/samples/dynamicRouting/validateDynamicURI/${sys:dyn-Endpoint}". The system-defined alias "${sys:dyn-Endpoint}" is replaced at runtime with the Dynamic URI from the header in the incoming request. For Example, if the incoming request contains the configured header name "dynHeader" and header value "ABC", then it will be redirected o, http://HOSTNAME:5555/rest/com/softwareag/mediator/samples/dynamicRouting/validateDynamicURI/ABC
Add "Outbound Authentication Transport" policy from Routing stage and configure "Authentication scheme as "Basic" and Authenticate using "Incoming HTTP basic auth credentials".
Save and activate the API.
Step 3: Invoking the API Gateway API with Credentials
Create a REST Project in SOAP UI with the Gateway endpoint "http://HOSTNAME:5555/gateway/DynRoutingDemoService/1.0/validateDynamicURI". Open the request from the GET method. Add the username/password (Eg: Administrator) in the Authorization Header. Add "application/json" as the Accept Header. invoke the request, you could see the response containing the below two lines.
{
"response_code": "200",
"response_message": "Success"
}
Troubleshooting
| Issue | Solution |
|---|---|
|
For Dynamic Routing using Header, Error Message |
Make sure the header and value as well as the default-route-to URL are set and configured properly |
|
For Dynamic Routing using Context Varibale, Error Message |
Make sure the user credentials provided in the request are valid to access the webMethods IS Service configured in the dynamic routing policy |
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
The below files can be found in the attachments.
- IS Sample services pacakge wmMediatorSamples.zip
Learn more
- To know more about Invoke webMethods IS policy in API Gateway, refer Invoke webMethods IS policy in API Gateway 10.2