IBM API Connect Tutorial: Part-2 IBM APIC Map Policy with example

Introduction

In this blog, we’ll explore some key features of IBM APIC Map policy. In order for our demonstration, let’s build a use case that covers some use cases ranging from simple to complex.

If you have not already gone through, please take a look at previous blogs on IBM API Connect:

• https://iteritory.com/install-ibm-api-connect-lte-in-local-windows-system/
• https://iteritory.com/ibm-api-connect-tutorial-part-1-develop-your-first-api/

Use Case

In this sample use case, we have an existing legacy web service that that returns the order information in XML format and isn’t standard. We’ll need to modernize this web service. We’ll use IBM APIC to wrap it with a modern REST compliant API. The data format of the new API will be JSON. Let’s take a look at the use case detail:

Legacy Service

Legacy service returns order data in XML format. We’ll use below data in our example

We’ll use https://www.mockable.io/ to mock the legacy web service that returns above data. Let’s mock the legacy web service by following below steps:

• Open https://www.mockable.io/ in browser. Click on Try Now! button.
• In the next window click on  DEFINE A NEW REST MOCK
• In the next window, let’s define the mock service. I have used following configuration on to mock the service:
  • Context Type: application/xml
  • Response Body: Paste the above XML content.

• Thereafter, save and start the mock. Use URL mentioned in the Path section to invoke mock web service. Take a look at the below sample mocking that I used while writing this article:

Modernized API

The modernized API will return order data in JSON format. We’ll use below format in our example. :

Mapping Document

We’ll use below mapping rules while implementing the new modernized wrapper API:

Implement the modernized API

Our goal is to invoke the legacy webservice (mocked above) using invoke policy and then we will use map policy to reformat the legacy response as per the mapping document and finally to produce the reformatted JSON output.

• Build the basic API

Sign in to the API Designer and build a basic API with following details:
Title: Map Policy Demo API
Description: IBM APIC Map Policy Demo API
Base Path: /map-policy-demo-api
Path: Keep the default
Security: Keep the default clientId.
Property: Change the value of target-url to the URL that we generated in https://mockable.io [refer to the previous section]

• Configure the Assembly section

Click on the invoke policy to open the configuration pane on the right. Scroll all the way down and locate Response object variable field. Enter var_resp. This variable will store the response from backend. We’ll reference to this variable from map policy.

Now, drag the Map policy from the left pane. A pop-up window will open. Click on the Pencil icon (highlighted below) to define the input data structure. Thereafter, click on + input button.

A new segment will open up. Populate this as segment as below:

Context variable: var_resp.body [This is the variable that will contain response from our legacy backend. Hence, we are defining it as input segment of map policy]

Content Type: application/xml

Definition: Click on the drop-down list and select inline schema. A new window will open up. Click on Generate from sample XML tab. Paste the XML document that we have above and click on Generate and then Done buttons. We’ll see the configuration something like below.

Click on Done button. You’ll now see that the APIC has created an input data structure from the sample data:

Now, let’s define the output structure. Click on the pencil icon on the output side of the map policy. Thereafter, click on + output button

A new segment will open up. Populate this as segment as below:

Context variable: message.body [This is the output context]

Content Type: application/json

Definition: Click on the drop-down list and select inline schema. A new window will open up. Click on Generate from sample JSONtab. Paste the XML document that we have above and click on Generate and then Done buttons. We’ll see the configuration something like below.

Click on Done button. You’ll now see that the APIC has created an output data structure from the sample data:

• Generic Instruction to configure the Map Policy

To use the map policy, follow the simple rules as mentioned below:

To connect an input field to an output field, click the grey dot (directly on the right) of the input field and then click the grey dot (directly on the left) of the output field. When you do that, a green line is drawn, linking the two input to the output.

You can also connect multiple input to a single output field. Thereafter, to configure the output, simply click on the green dot on the left of the output field, a window will open and you can configure, write gateway script etc.

In below sections, let’s cover some of the complex mapping logics and how those are implemented:

• Mapping of Address field

In the address field, we are concatenating multiple data points from input XML. It’s not that complex. Below is the the YAML snippet with Gatewayscript from the same:

• Mapping of lineStatus field

For the lineStatus field, we need to execute a logic to check what is the incoming status and accordingly we”ll set the output value. In this particular mapping, you will also see how to use foreach loop in map policy. Below is the the YAML snippet with Gatewayscript from the same:

• Mapping of totalLines field

In this field, we are running some logic as well as we counting the total number of order lines. In the code snippet below, you will notice an expression $(0). This expression is basically total accumulated value in the output field. If see below, the for each order line in input message, we are adding +1 to $(0) which keeps on getting accumulated. At the end of the for loop, we get the total number of order lines.

• Mapping of orderValue field

This field mapping is a little more complex where we count the total order value for ACTIVE order lines from the input message.

The modernized API will return order data in JSON format. We’ll use below format in our example. :

Now that we have completed mapping requirements as per the mapping document, let’s see how the mapping policy looks like:

Test the IBM APIC Map Policy API

Let’s run the API we just implemented above by using the triangular Publish button from the toolkit (if you are not use which button, please check my previous blog https://iteritory.com/ibm-api-connect-tutorial-part-1-develop-your-first-api/) .. This will publish the API in my local test environment.

To test the API, I’ll use POSTMAN tool.

The transformed API response is as below:

Github Link

You can find the API Yaml and the mapping document in the github repo: https://github.com/msadrud/ibm-apic-map-policy