Tutorial: Mapping JSON Content

This tutorial shows you how to map message content from one format or schema to another format or schema.

Before You Begin

This task can be completed by users who are assigned one of the following roles:
  • Catalog Owner
  • Catalog Administrator
Note: The Sandbox catalog must be configured to use either a DataPower® Gateway (v5 compatible) or a DataPower API Gateway or both. See Creating and configuring Catalogs.

About this tutorial

In this tutorial you are going to complete the following lessons:

Create a New API

Take the following steps to create a new API.

  1. Log in to API Manager.
  2. In the Welcome page, click the Develop APIs and Products tile.

    APIM screen

  3. Click Add > API.

    API add menu

  4. Select New OpenAPI. Click Next.

    New API

  5. Specify basic information about the API.
    1. In the Title field, enter Mapper.
    2. Enter /map in the Base Path field.
    3. Enter 1.0.0 the Version field.

    Create API

  6. Click Next.
  7. Make no changes on the Secure screen. Click Next.

    Secure API

  8. You see the progress as the new API gets created. When it is done, you see a Summary. Click Edit API.

    New API summary

  9. The Design tab for the draft of your API definition opens.
  10. Scroll down. Select application/json in the Consumes section and also in the Produces section.

    Set Consumes and Produces

  11. Leave the remaining fields unchanged. Click Save.
  12. Click Paths on the navigation bar.
  13. Click Add.

    Paths

  14. In the Path name field of your newly created Path, enter /jsonmap.

    Paths

  15. In the Operations section, click Add.
    1. Select POST from the list.
    2. Click Add.

    Choose opoeration

  16. Click Save.
  17. Click /jsonmap in the list of available paths.

    Choose opoeration

  18. Click the POST operation.
  19. Click Add in the Parameters section.

    Get configuration

  20. Take the following actions.
    1. Select REQUIRED.
    2. Enter body in the NAME field.
    3. Select body in the LOCATED IN field.
    4. Select string in the TYPE field.

    POST configuration

  21. In the Response section, change the DESCRIPTION for the 200 response code to 200 OK.

    Post configuration

  22. Click Save.

Map JSON Content

  1. Click Assemble.
  2. Delete the existing policy on the canvas by hovering your cursor over the policy and then clicking the Delete icon The Delete policy icon; if you are using the DataPower API Gateway, the policy is an invoke policy whereas if you are using the DataPower Gateway (v5 compatible), the policy is a proxy policy.

    Input map policy

  3. From the action palette, drag the Map action onto the dashed box that is displayed on the canvas. The configuration pane opens automatically.

    Input map policy

  4. Click the Edit inputs icon. Edit icon
  5. Click + input.
  6. Configure the input according to the following table:
    Table 1. JSON input
    Property Value
    Context variable request.body
    Name input
    Content type application/json
    Definition Inline schema

    Map inputs

  7. A dialog pane opens. Click Generate from sample JSON.

    Generate inline schema

  8. Paste the following sample JSON into the box. 
    
{"order":
{"customer":
{"name":
{
"firstname":"John",
"middlename":"Q",
"lastname":"Smith"
},
"address":
{
"line1":"550 King St",
"line2":"Dept 5",
"city":"Littleton",
"state":"MA",
"country":"USA",
"code":"01460"
}
}
},
"items":
[{"item":"shoes", "color":"black", "qty":2, "price":23.50},
{"item":"socks", "color":"argyle", "qty":2, "price":3.95},
{"item":"pants", "color":"grey", "qty":1, "price":48.00}]
}

    Input sample JSON

  9. Click generate.
  10. The OpenAPI code to describe the schema appears. Click done. The dialog box closes.
  11. Click Done to complete the Input map configuration.

    Map input config

  12. Click the Edit outputs icon The Edit outputs icon in the Output column of the property sheet.

    Map input config

  13. Click + output.
  14. Configure the input according to the following table:
    Table 2. JSON output
    Property Value
    Context variable message.body
    Name output
    Content type application/json
    Definition Inline schema
  15. A dialog pane opens. Click Generate from sample JSON.
  16. Paste the following example JSON into the box. 
    
{"order":
{
"date":"12-12-12",
"customer": "John Smith",
"address":
{
"street":"king",
"citystatezip":"lit MA 01469",
"country":"USA"
},
"items":[{"type":"shoes", "color":"black", "qty":2, "price":23.50}]
}
}

    Sample output JSON

  17. Click generate.
  18. The OpenAPI code to describe the schema appears. Click done. The dialog box closes.
  19. Click Done.

    Output map config

  20. Click Save.

    Map schemas ready

  21. Click the handle alongside the date field in the Output column. A dialog box opens.
  22. Enter the following JavaScript code in the box; new Date().toGMTString(), then click ok.

    Date field code

  23. Click the handle alongside the firstname field in Input and click the handle alongside the customer field in Output.
  24. Click the handle alongside the middlename field in Input and click the handle alongside the customer field in Output.
  25. Click the handle alongside the lastname field in Input and click the handle alongside the customer field in Output.

    Connect customer node

  26. Click the handle alongside the customer field in Output. A dialog box opens.
  27. Enter the following code in the box. Click ok. 
    var name = $(input.order.customer.name.firstname) + ' '; 
  if($(input.order.customer.name.middlename)) {
  name += $(input.order.customer.name.middlename) + ' ';}
  name += $(input.order.customer.name.lastname);
  name

    Customer output code

  28. Click the handle alongside the address line1 field in Input and click the handle alongside the street field in Output.
  29. Click the handle alongside the address line2 field in Input and click the handle alongside the street field in Output.

    Street output map

  30. Click the handle alongside street in Output. This opens a dialog box.
  31. Enter the following code in the box. Click ok. 
    var street = $(input.order.customer.address.line1) + ' '; 
  if($(input.order.customer.address.line2)) {
  street += $(input.order.customer.address.line2);}
  street

    Street output code

  32. Click the handle alongside the city field in Input and click the handle alongside the citystatezip field in Output.
  33. Click the handle alongside the state field in Input and click the handle alongside the citystatezip field in Output.
  34. Click the handle alongside the code field in Input and click the handle alongside the citystatezip field in Output.

    City State Zip output map

  35. Click the handle alongside the citystatezip field in Output. A dialog box opens.
  36. Enter the following code in the box. Note that the variable references are positional; $(1) refers to the first mapped value (input.order.customer.city), and so on. Click ok. 
    $(1) + " " + $(2) + " " + $(3)

    City State Zip output code

  37. Click the handle alongside the items field in Input and click the handle alongside the items field in Output. An additional wire is drawn automatically.

    Item mapping

  38. Click add property after the closing array bracket - ] - of the Output items array.

    Add property

  39. Enter total in the field that is labeled property. Set the type to float. Click the + icon.

    Add property

  40. Click the handle alongside the items field in Input and click the handle alongside the total field in Output. Note that the system automatically adds a connector to the map.

    Map total

  41. Click the handle alongside total in Output. This opens a dialog box.
  42. Enter the following code in the box. This code sums the items for each order. Click ok. 
    $(0) + ($(input.items.price) * $(input.items.qty))

    Code total

  43. Click the Save icon to save these changes.
  44. Click Source.
  45. Drag the highlighter to the end of the Source.

    Source display

  46. Locate the code where total is calculated.

    Calculation of total

  47. Insert a new line with the code foreach: input.items.

    Calculation of total adjusted

  48. Click the Save icon to save these changes.

Testing your API definition

Note: Due to Cross-Origin Resource Sharing (CORS) restrictions, the assembly test tool cannot be used with the Chrome or Safari browsers on the macOS Catalina platform.

To test your API definition by using the API Manager test tool, complete the following steps:

  1. Click the Assemble.

    Assemble page

  2. Click the Test icon The Test icon. The test tool opens.
  3. Click Activate API.

    Test setup

  4. In the Operation field, select post /jsonmap.

    Test select op

  5. In the body field, enter the following JSON text.
    
{"order":
{"customer":
{"name":
{
"firstname":"John",
"middlename":"Q",
"lastname":"Smith"
},
"address":
{
"line1":"550 King St",
"line2":"Dept 5",
"city":"Littleton",
"state":"MA",
"country":"USA",
"code":"01460"
}
}
},
"items":
[{"item":"shoes", "color":"black", "qty":2, "price":23.50},
{"item":"socks", "color":"argyle", "qty":2, "price":3.95},
{"item":"pants", "color":"grey", "qty":1, "price":48.00}]
}

    Test select op

  6. Click Invoke. The response is displayed.
    Note: If you are using a self-signed certificate, you might be prompted to visit a provided URL. Click the link and then accept the certificate before returning to API Manager and clicking Invoke again.

    Test success

    Test success

Manage your API definition

Now that your new API works correctly, you can manage this API. To see your immediate options, take the following steps.

  1. Click the Develop icon Develop icon on the navigation bar.

    Navigation bar

  2. Click the Options icon The manage icon alongside the Mapper API.

    Manage API

  3. Select Download.

What you did in this tutorial

  • Created a new API
  • Mapped content from one JSON schema to another schema.