The examples presented in this chapter will require an installation of API Connect or API Connect LTE to configure and execute them. A working knowledge of XSLT and JavaScript will also be extremely beneficial in the later sections of this chapter.
Introduction to API Connect pre-built transformation policies
In Chapter 4, API Creation, you were introduced to pre-configured, or built-in, policies within the policies of an API flow. Of the many to choose from, some can be used to transform your data either on the request or response flow. As you are configuring the Gateway policies of your API, you will notice that all of the pre-defined policies on the left of the page are logically grouped based on the type of functions that they perform. You will notice a Transforms grouping, which will contain five different policies that you can use within your Gateway policy flow to transform your data. Each one will perform a specific type of transformation or pertain to a specific data format to transform to and from. In addition to these five policies listed under the Transforms heading, the GatewayScript policy can also be very useful in transforming data. This policy is listed under the Policies heading. Figure 8.1 shows these different policies that we will be working with in this chapter to perform data transformations highlighted in yellow:

Figure 8.1 – Pre-defined policies for transformations
Just as you saw in Chapter 4, API Creation, you will simply drag the desired policy onto the Gateway policy flow and configure it appropriately. We will cover each of these policies in this chapter, describing when you might use them and how. We will start with the more simple use cases and build up to the more complex. Let’s get started with the Map policy.
Using a Map policy
The Map policy is perhaps one of the most user-friendly methods provided to transform request and response data. This policy provides a way to define your data structure or invoke the schema from your Definitions configuration within the API configuration itself. Once the to and from data definitions are defined, this policy provides a convenient drag and drop feature to simply connect the fields to be mapped. The Map policy also provides the ability to add conditional logic, data formatting, calculations, and more. Although this policy can provide all of these features, you should use some restraint when being tempted to get too complex with it as the simplicity may come at a cost. That cost could be the performance or your API.
To explain and demonstrate how to configure the Map policy, let’s take a simple order service where we are exposing the API as a RESTful service that expects JSON as the request. The backend, or target service, however, has not been modernized and expects the request to be in XML format. This is a relatively small request and there is a simple 1:1 conversion from the JSON fields to the XML fields. This would be a good opportunity for us to take advantage of the built-in Map policy provided by API Connect.
Our example API that is configured to receive JSON in the request message is expecting the following format:
{
“createOrder”:{
“customerId”:”187562X”,
“itemNumber”:”12876″,
“itemQuantity”:2,
“itemDescription”: “APIC widget”,
“orderTotal”:12.75
}
}
The target service that our API will forward requests to is expecting XML as the request message format in the following request message format:
<createOrder>
<customerId>187562X</customerId>
<itemNumber>12876</itemNumber>
<itemQuantity>2</itemQuantity>
<itemDescription>APIC widget</itemDescription>
<orderTotal>12.75</orderTotal>
</createOrder>
You can see the relationship between these two messages and mapping should be evident. We can accomplish this within our API flow using the Map policy. Let’s take a look at how we do this:
- To begin, we must be on Gateway tab within the Policies section of the API. Here we can simply drag the Map icon onto our flow before the invoke policy so that the message is transformed before invoking the target service, as shown in Figure 8.2:

Figure 8.2 – Dragging the Map policy onto the policies flow
Once the map policy is within our flow, the configuration panel should become visible. If you do not see the configuration panel for the map policy, clicking the policy on the main panel will bring it up.
2. From the configuration screen, we can begin to define our input message by clicking on the pencil icon next to the Input label, as shown in Figure 8.3:

Figure 8.3 – Map policy configuration screen
3. From this screen, clicking the Add input button will render the screen where you can now define your input message format. You will notice several fields that you can configure, the first being the Context variable. This is where you can specify which variable contains the message that we are defining. For our example, we will be working with the request message as it came into the API that is stored in the request.body variable, and which just so happens to be the default, so we will leave that as is. We can also leave the Name field as the default value of input.
4. The next step is to define the Content type for this incoming message. Since we will be expecting a JSON request, this should be set to application/json from the dropdown. You will notice that the dropdown contains a list of several values for the content type that can be set to reflect your incoming message and content-type header as your use cases see fit.
5. Now that we have defined where to find the message to transform and the content type, we can define the data structure itself. If you haven’t guessed it already, we will begin this configuration at the last field displayed on this screen, labeled Definition. Looking through the values presented in this dropdown, you will notice a wide array of values that can be used to define your input message. Many will simply be a data type such as integer, string, or float, which can be used if you were defining a single field. In our use case, we will be defining an entire input JSON message. For this, we will select Inline schema so that we can define our incoming message. Once selected, a new popup will appear, allowing you multiple options on how to define your schema.

Figure 8.4 – Provide a schema popup for inline schemas
As shown in Figure 8.4, you can define your schema in YAML or JSON format. Alternatively, if you already have a sample JSON or XML file, you can generate the schema based on the sample. To make things simple, you will use Generate from sample JSON. Click on Generate from sample JSON and paste in the JSON input shown earlier in this section. Figure 8.5 shows an example:

Figure 8.5 – Generating schemas using JSON
After pasting the JSON, click the Generate button to create the schema.
Your schema should now look as follows:
description: ”
type: object
properties:
createOrder:
type: object
properties:
customerId:
type: string
itemNumber:
type: string
itemQuantity:
type: number
itemDescription:
type: string
orderTotal:
type: number
example: >-
{“createOrder”:{“customerId”:”187562X”,”itemNumber”:”1
2876″,”itemQuantity”:2,”itemDescription”:”APIC
widget”,”orderTotal”:12.75}}
6. At this point, we have defined the basic configuration for our Map policy, as shown in Figure 8.6:

Figure 8.6 – Basic Map policy configuration