webMethods API Gateway tutorial
Author: Rizwan, Mohammed (Mohammed.Rizwan@softwareag.com)
Supported Versions: 10.3 & above
Overview of the tutorial
In this tutorial we will be talking about the API Mocking capabilities in API Gateway. We will discuss the following methods of mocking in detail.
- Static mock response
- Dynamic mock response
- Condition based mock response
- ESB (webmethods IS service) driven mock response
Required knowledge
The tutorial assumes that the reader has,
- a basic understanding of API Gateway as a product
- a good knowledge on APIs and their definitions
- a hands on experience on invoking the APIs in API Gateway
Why?
API Mocking is nothing but the imitation of real API. It simulates the behavior of real API but in a more controlled manner. Let's see a couple of scenarios where we need a mocking response for an API. Let's say in typical product development, the back-end and UI development is happening in parallel. The UI developers need not wait for a full-fledged API instead they can work with the mock response and thus makes the UI development independent. Secondly, in a test-driven development, the testers need not to wait for the development completion of the APIs to start with their automation of tests rather they can automate all the tests with mock responses. Moreover, the API Provider can expose the APIs to the clients before the actual implementation is done and provide the users with mock responses in an agile manner.
Prerequisite steps
Complete the below prerequisites to make you ready to get into the details of API mocking in API Gateway.
- Install API Gateway of version 10.3
- Install Software AG Designer of version 10.3
- Install postman REST client
- Create and activate a REST API in API Gateway using the attached open API file (mockingService.json)
- Install the supportMocking.zip IS package in IS server
Details
API without mocking
First let's see the behavior of an API before enabling mocking whose endpoint is down or functionality is not implemented yet and then the configuration of API mocking in API Gateway. With mocking disabled, when the API is invoked, the API Gateway routes the request to the non-existing native service which results in returning an error response to the user saying native service is down as below.
This behavior is not desirable in situations like parallel development and test-driven approach.To make more sense to this scenario, mocking should be enabled to return the mocked response instead of downtime exception. API mocking can be enabled by clicking the 'Enable mocking' button in the API details page. When mocking is enabled for an API, API Gateway sets the mocked response as below.
Sets the example as default mocked response if available in the resource/method/response-status-code/content-type level
Generates a sample response from the JSON / XML schema if available in the resource/method/response-status-code/content-type level and sets the generated sample as default mocked response
No default mocked response will be set if an example or schema is not available, but the default mocked response can be manually added or updated on the API details page
Once mocking is enabled, the default mocked response for all the available resources is generated from the sample or schema which can be seen under 'API Mocking' in API details page as below
Static mock response
Here let's see a basic scenario where the mock responses are static. The user would not control the content of the response instead they would choose which response has to be sent based on the Accept header and status code query parameter. The below screenshots show that the API Gateway returns a static mocked response to the user based on the 'Accept' header.
The below XML mock response is returned when the Accept header is application/xml.
By default API Gateway sends the 200 status code. The user also can send the status code by setting the query parameter expectedStatusCode in the URL as below.
Dynamic mock response
Here we will discuss a dynamic mock response whose content is controlled by the user and the response is dynamically generated based on the variables sent in the request. The mock response is configured to contain many custom replacers. A custom replacer is used to replace the custom variables with the values derived from the request headers, query parameters, and request body. The custom replacer would have the below format.
${request.<ConditionParameter>.<Key|JsonPath|XPath>}
The custom replacers fall in the below categories.
- ${request.header.<headerKey>} → Replaces with the value of the headerKey from the request headers
- ${request.query.<queryKey>} → Replaces with the value of the queryKey from the query parameters in the request URL
- ${request.body.<JsonPath|XPath>} → Replaces with the value of the <JsonPath|XPath> from the request body
- ${request.path.<pathID>} → Replaces with the value of the pathID from the path parameters in the request URL
For instance the below-mocked response contains multiple custom replacers which replace the variables from the body of the request.
The below screenshot shows the dynamically generated mock response after all the custom replacers are replaced based on the request body content.
Condition based mock response
In this case the API Gateway provides an option to configure a condition in the operation level of the API under API mocking. The conditions are based on the request body, headers, query parameters and status codes. During invocation the conditions will be matched with the request variables and a corresponding mock response will be returned to the user. To add a condition, go to API Mocking, select the resource or operation and click Add Conditions button.
The description of each field in the condition is given below.
Condition name → An user defined name to describe the condition
Condition parameter → Source of the condition. Possible values are Body, Header and Query parameter
Key → It is the name of the header or query parameter and for body it is a JSON path or an XML path
Value → The value of the condition. Additionally, you can type an * (asterisk) to ignore the value specified in this parameter and the condition is satisfied based on the value specified in the Key parameter
Status code → Status code to be sent in the mock response
Add Response Header → Adds the response headers to be sent in the response
Add Content-type → Adds the content type along with its response payload. API Gateway returns the response payload based on the accept header
Header based condition
Below is the sample condition based on a header parameter requestFrom
If the request doesn't have the requestFrom header the no condition would be matched and API Gateway sends the default mocked response as below.
In the below request the condition is matched as the request contains the header requestFrom with value API-Portal, so the API Gateway sends the mock response configured for that condition.
Query parameter based condition
Below is the sample condition based on a query parameter queryParam.
In the below request the condition is matched as the request contains the query parameter queryParam with value queryValue, so the API Gateway sends the mock response configured for that condition.
Body based condition
Below is the sample condition based on the JSON request body.
In the below request the condition is matched as the request contains the key status with value success in the request body, so the API Gateway sends the mock response configured for that condition. The mock header mockedResponse also sent in the response.
ESB (webmethods IS service) driven mock response
If the user's use case is not met by using any of the mocking methods mentioned above, the user can configure an ESB service to achieve the desired behavior. Say, for example, the user wants to return the request body content in the upper case. As a first step to meet the use case create a flow service with the specification reference 'apigateway.specifications:mockService' in Software AG Designer.
Orchestrate all the necessary mappings between the input and output pipelines of the included pub flow services. The flow of services would convert the request body content to upper case and return the output. The mapping for pub.string:bytesToString is given below.
The mapping for pub.string:toUpper is given below.
The mapping for pub.string:stringToBytes is given below.
Configuration in API Gateway
Go to API page → API Details → API mocking. Configure the above created flow service in Invoke service field.
When the API is invoked, the mock response resulted from the ESP service will be returned.
Execution preference
If multiple methods of mocking are configured for an API, the API Gateway would follow the below order for selecting the appropriate mocking method to return the response.
- If any of the conditions for the invoked operation satisfies, API Gateway returns the associated mocked response
- If a condition is not satisfied or none of the conditions for the invoked operation are satisfied and if an ESB service is configured for the API, then API Gateway invokes the ESB service and returns the ESB service response
- If a condition is not satisfied or none of the conditions for the invoked operation are satisfied and if an ESB service is not configured for the API, then API Gateway returns the default mocked response
Limitations
- API mocking is not supported for Websocket APIs
Try Out
To access API Mocking first, you need to create and activate a REST API in API Gateway using the attached open API file (mockingService.json).To invoke the methods you need to create the header, body and query-based condition in API Mocking in the API Gateway and using the client user interface to invoke the methods and to get the response. We have already created an API and invoked the methods the response is saved in a Postman. So you need not create an API Mocking in API Gateway.
Instead of you creating an API in API Gateway. We simplified the work we already created the API as the name "API_Mocking_Demo". We upload API_Mocking_Demo API in cloud instances. Click the link to login into the API Cloud: https://www.softwareag.cloud/site/product/webmethods-api.html.
Once you click the link you must be login into the WebMethods API Cloud using the below the username and password
Username:single4
Password:Test123$
After login into the WebMethods API Cloud go to the API Gateway -> APIS -> API_Mocking_Demo.
To invoke the method in API, we have to create a request in the client user interface. Now we created a request in the client User interface to make it more accessible for you. Here, we used Postman UI to invoke the method.Click the below link.
Click here: https://github.com/RevathyLatha/Mocking
Once you click this link the GitHub page opened. Click the clone button and Clone the repository into your local system.
To invoke the method we want client user interface. If you don't have a copy of Postman, you can download a copy from: https://www.getpostman.com/downloads/
After you have Postman running, you'll need to import files. To do that, complete the following procedure from within Postman:
In Postman,Click Import
In the Import dialog box, click Choose Files
Select the API Mocking Collection files and then click Open. The file get imported in your postman as API Mocking Collection.
**NOTE:** ESB service configuration is not working
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
- Sample Open API file for the sample REST API used in this tutorial
- Sample IS package for generating ESB driven mock response
mockingService.json (3.55 KB)
supportMocking.zip (2.31 KB)
Further read:
Get to know the details on how the assets in API Gateway like APIs, Policies, Applications, etc. are moved from one stage of SDLC to another using Asset build environment (ABE) and webMethods Deployer: Staging, Promotion and DevOps of API Gateway assets