Skip to main contentDemoHub - Cloud Pak for Integration

APIC Dev Jam Lab 5 - Advanced API Assembly

In the previous labs, you have been working with an API that acts as a pass-through to a microservice application.

In this lab, you will expand the product offerings for ThinkIBM. In addition to the Inventory API, ThinkIBM wishes to provide APIs that offer financing and shipping logistics to consumer applications. Your goal is to utilize existing enterprise and public assets to create these API offerings.

In this tutorial, you will explore the following key capabilities:

  • Create a new API, including object definitions and paths.

  • Configure an API to access an existing SOAP service.

  • Import an existing API from an OpenAPI definition document (a.k.a Swagger).

  • Map data retrieved from multiple API calls into an aggregate response.

  • Use GatewayScript directly within an API assembly.

APIC Dev Jam Series

The APIC Dev Jam Series is a hands-on workshop with lab exercises that walk you through designing, publishing, and securing APIs. This workshop is for API developers, architects, and line of business people who want to create a successful API strategy. There are 8 labs and each is 30 minutes long. Make sure you choose enough time in your reservation to get through all the labs! 

[NOTE: ][This demo environment contains a full API Connect installation in Cloud Pak for Integration. The login information to the APIC cluster will be sent in a separate email when you reserve the instance. Use Google Chrome, Firefox or Microsoft Edge to access the cluster using the credentials supplied. Make sure you login using API Manager User Registry not Common Services registry.]

Prerequisites: Labs 1-4

Create and Define the Financing API (REST to SOAP)

ThinkIBM wants to give its customers the ability to calculate financing payments. There is already a legacy SOAP-based application which will do the calculation, but it should be exposed to consumers as a modern RESTful API. In this section, you will create a new OpenAPI definition for the financing API.

  1. From the left navigation menu, click [Develop.]

  2. Click [Add] and choose [API].

     tutorial html 35bc8347ebf9f3c4

  1. Select [New OpenAPI] and click [[Next.]]

     tutorial html 8027761d9675e244

  1. Fill in the form for Create New OpenAPI with the following values: 

    [Title: financing]

  Name: financing

  Base Path: /financing

  Version: 1.0.0

Click **Next**.

     tutorial html 6dab5b579d7af76

  1. Leave all default values and click [[Next. ]]API Connect will generate a new OpenAPI definition for the financing API and provide a summary with the performed activities.

    tutorial html fb454c7ee948008d
  2.  Click  [Edit API ]to customize the API.**

  3. Create the model definition for the new API. These definitions are used in a few places. Their primary role is to serve as documentation in the developer portal on expected input and output parameters. However, they can also be used for data mapping actions. Click [Definitions] from the API Designer menu on the left. Then, click [Add] to create a new definition.

    tutorial html f584c2696c3ce084

  1. Enter [paymentAmount] for [Name] and leave the definition [Type] set to [object].

  2. Click [Add] in the [Properties] section.

    tutorial html 332203efe7e366f5
  3. Edit the property values using the following values:

    Property Name: paymentAmount

    Type: float

    Example: 199.99

    Description: Monthly payment amount

    The page will look like this:

tutorial html c600b4bb8ec6adee

The property will be utilized in the Path you create next.
Click **[Save]** to go back to the main API
  1. Click [[Paths]] in the navigation menu on the left. Then click [Add] to create a new path.

    tutorial html f3f04d5e1fde784d
  2. The Path screen is loaded. Edit the [[Path name]] to be [/calculate]. [Note:] [Recall that our Base Path for this API is `financing`. This new path will be appended to the base, creating a final path of          /financing/calculate.]**

  3. Click [[Add]] in the Operations section to define the operation to support under the path.

    tutorial html 32f5ad5e80b58cd5
  4. From the [Add Operation] menu, select the [Get] operation and then click [Add]

    tutorial html aae3e2ff9be52791
  5. Click [Save]. You will be redirected to the main API Editor to continue.

    tutorial html 66cc80ef2c7d855b
  6. Click the [/calculate] path we just created.

    tutorial html 864cc1225031590a
  7. Click the [GET] operation to add the request parameters. This defines the input to the API request. Since this is a GET request, you will add the required request parameters to the query component of the URI.

    tutorial html 2cf0c1234fbd4aa3
  8. Scroll down to the Parameters section within the operation config. Click [[Add]] in the [[Parameters]] section. You are actually going to need three total parameters for this operation, so go ahead and click the `Add` button two more times to add the parameter templates.

    tutorial html 1e46988677afe0a
  9. Edit the parameters to set the values:

**Required** **Name** **Located In** **Type** **Description**
-------------- ---------- ---------------- ---------- --------------------------
yes amount Query float amount to finance
yes duration Query int 32 length of term in months
yes rate Query float interest rate

Once you have entered the values, the screen will look like this:

tutorial html 2fc0008e5f75928e

  1. Set the schema for the response. Click Add in the [Response] section. Enter [[200]] for [[STATUS CODE]]. Since we already defined the [paymentAmount] definition, select it from the drop down list for [[SCHEMA]]. You will find the [paymentAmount] definition at the bottom of the list. For [[DESCRIPTION]] enter [[amount calculated successfully]] tutorial html f51180a01dc389af

  2. Click [[Save]] to save the API definition.

    tutorial html a0106fbcef024d0

Map the API to a Service WSDL

Import the legacy Financing SOAP service WSDL and map it to the RESTful API definition.

Attach a Service WSDL

  1. Click the [Target Services] option in the left column menu palette from the [financing 1.0.0] API Design screen

  2. Click [Add] to import the web service from the legacy financing service.

    tutorial html ebb6419fc4fb979a
  3. Download the calculate.wsdl and then Click [Browse] to select [[calculate.wsdl]] located in where you downloaded it on your machine.

    tutorial html e10ec45733dfce99

  You will get a success message and the service included in the WSDL will be displayed.

    tutorial html 6a8444e050b87ad3

  1. Select [financingService.] Then click [Submit].

    Build the Financing API Assembly

  2. Click [[Assemble]] to access the assembly editor.

    tutorial html 7ecdd003a7db2e23
  3. In the processing pipeline, mouse over the [[invoke]] policy and click the [[trashcan]] icon to delete it.

    tutorial html d05e099dd7e132b4
  4. Scroll down to the bottom of the policy menu and drag and drop the [financing web service operations] to processing pipeline.

    tutorial html 771de22ad92a31fb
  5. Now you are going to modify the input and output map policy for mapping your REST API into SOAP.

    tutorial html 4a933c8c317bbd97
  6. Since we are using the new API Gateway, we will need to instruct it to use the newer version of the policies in the flow (map, invoke, map). Click Source to go to the OpenAPI definition of your API.

    tutorial html 35460e46cf085196
  7. Scroll down to map and insert [[version: 2.0.0]] right below it. 

    tutorial html 66473f670a224c38
  8. Scroll down to invoke and insert [[version 2.0.0]] right below it. Skip if the version 2.0.0 is already populated.

    tutorial html d480dfb5896607c6
  9. Now go to the last map and insert [version: 2.0.0] right below it. Click [[Assemble]] to go back to the gateway flow designer. Skip if the version 2.0.0 is already populated.

    tutorial html 80b968197ef6f435
  10. In order to consume a SOAP-based service from your REST-based API, you need to map the query parameter inputs that were previously defined as part of the GET /calculate operation to a SOAP payload. To do so, click the [[financing input]] map policy on our pipeline to open the map editor.

  [[Tip: Click on the `+` icon to make the editor window fill the screen.]]

  1. Click on the [[pencil icon]] in the [[Input column]].

    tutorial html 9d82765fc8e50237
  2. Click [[+ parameters for operation...]] and select the [GET Calculate operation].

    tutorial html 9dad0a59d5e53a96

  The Map editor will automatically pull in the request parameters that you defined earlier.

  1. Click [Done] to return to the map editor.

  2. For each of the Input query parameters, map them to their respective SOAP Output elements.

  To map from an input field to an output field, click the circle next to the source element once, then click the circle next to the target element. A line will be drawn between the two, indicating a mapping from the source to the target.

tutorial html e18d417ab873efe0
  1. Click [[`X`]] in the map editor to return to the policy pipeline.

  2. Click the [[invoke policy]] to open its editor.

  3. The SOAP service URL has already been set for you during the service import when we create the API.

    tutorial html 8d30f4d88ab4c2bf
  4. Click [[`X`]] to return to the policy pipeline.

  5. After the Financing Web Service is invoked, you need to map the SOAP response into a JSON object.

    You already defined the response object called [[paymentAmount]]. To do the map, click the [financing output] map policy on the pipeline to open the map editor.

  1. Click the [[pencil icon]] to set the output object schema.

  2. Click the [+ outputs for operation...] option and select the [[GET /calculate operation]].

  3. Set the [[Content type]] configuration option to [[application/json]], and then click [[Done]] to return to the map editor.

    tutorial html 4e9aa0f663bd6c06
  4. Click the [[circle next to the paymentAmount source element]] once, then click the [[circle next to the target element]]. A line will be drawn between the two, indicating a mapping from the source to the target.

    tutorial html f2e452da44248e01
  5. Click [[`X`]] in the map editor to return to the policy pipeline.

  6. Click [[Save]] the API definition.

  7. Click [Develop] in the navigation menu to return to the list of APIs and Products in your system.

    tutorial html a810481f55373ff0

Import Logistics API

In this lab section, we will be adding a new API called logistics which will provide helper services around calculating shipping rates and locating nearby stores. Rather than require you to build the entire API from scratch again, you will see how you can import and modify an existing OpenAPI definition.

Import the OpenAPI Definition

  1. Click [Add] and select [API.]  

    tutorial html 44524c2a518bf56e
  2. From the Create API wizard, select [[Import: Existing OpenAPI]]. Then click [[Next]].   tutorial html 5515164592670a5f

  3. You will need logistics.yaml file for this step. Fron another browser window download the file using this link logistics.yaml

    Click `Browse` in the [[Import from file]] window, and select the downloaded logistics.yaml file.

    tutorial html 2ec43e484c5482b0
  4. Click [[Next]] in the confirmation window.

  5. Click [[Next]] one more time [[without selecting the option Activate API]] since we still need to make some updates.

  6. Click [[Edit API]] in the [[Summary]] page to go to the API editor.

Configure payload to be stored in Analytics

  1. From the API menu, select [[Activity Log]]. In the [[Content]] drop-down, select [[payload]]. A pop up window will be displayed, asking to enable buffering. Click [[Continue]].

    tutorial html e8ffcd636704e49b
  2. Set the [[Content on error]] drop-down to [[activity]]. Click [[Save]].

    tutorial html 1b4e90745e45c224

Create an Orchestration Assembly

The logistics API provides resources for calculating shipping costs and locating the nearest store for pickup. In this section, you will configure the assembly for the shipping calculation resource. Your API assembly will call out to two separate shipping vendors and provide a consolidated response back to the consumer.

Create the Logistics API Assembly

  1. Switch to the [[Assemble]] tab and remove the [[invoke]] policy by hovering over it and selecting the [[trashcan icon]].

  2. Click and drag the [[Operation switch]] policy to flow pipeline in the right.

  3. The switch editor will open with a single case with case 0 created by default.

  4. Next to case 0, click [search operations...] to show the drop-down list of available operations.

  5. Select the [shipping.calc] operation.

  6. Click the [+ Case] button to add a second case for the [[get.stores]] operation.

  7. Click [X] to close the operation switch configuration editor and then click [[Save]]. You should see two new processing pipelines created on your `operation-switch` step - one for each case:

    tutorial html 2805ad613d2ba436

Configure the shipping.calc Case

This operation will end up invoking two separate back-end services to acquire shipping rates for the respective companies, then utilize a map action to combine the two separate responses back into a single, consolidated message for our consumers.

  1. Add an [[invoke policy]] to the [[shipping.calc case]].

  2. Edit the [invoke] action with the following properties:

    • [[Title: invoke_xyz]]

    • [[URL: $(shipping_svc_url)?company=xyz&from_zip=90210&to_zip={zip}]]

    • [[Stop on error: unchecked]]

    • [[Response object variable (scroll to the bottom): xyz_response]]   tutorial html 8c4d5816115227c1     tutorial html 3a71962c80162408

    • [Note: The parameter provided here is a reference to the zip parameter defined as input to the operation. The portion of the URL will get replaced by the actual zip code provided by the API consumers. ]

  3. Hover over the [[invoke_xyz policy]] and click [[clone]] to add another invoke action:  

    tutorial html c099b7fb4e29d1ef  

  4. Edit the new invoke policy with the following properties:

    • [[Title: invoke_cek]]

    • [[URL: \$(shipping_svc_url)?company=cek&from_zip=90210&to_zip= ]]

    • [[Response object variable: cek_response]]  

      tutorial html 84608c0a3a93f935

  tutorial html e4fed02337332021

  1. Add a [[map policy]] after the last invoke and then click it to open the editor.   tutorial html df80d082c629e3eb  

  2. Click the [[pencil]] at the top of the Input column, then click on the [[+ input]] button. Enter the following input configuration:

    • [[Context variable: xyz_response.body]]

    • [[Name: xyz]]

    • [[Content type: application/json]]

    • [[Definition: #/definitions/xyz_shipping_rsp]]

  3. Click the [[+ input]] button again to add another input. Specify the following input configuration:

    • [[Context variable: cek_response.body]]

    • [[Name:cek]]

    • [[Content type: application/json]]

    • [[Definition: #/definitions/cek_shipping_rsp]]

  4. You now have two inputs assigned to the map policy:   tutorial html 1cecd20554b4f15b

  5. Click [[Done]] to return to the editor.

  6. Click the [[pencil icon]] at the top of the [[Output]] column and then click [[+ outputs for operation...]] and choose the [[shipping.calc]] operation.

  7. Set [Content type] to [[application/json]].

  8. Click [[Done]] to return to the editor.

  9. Complete the mapping. To map from an input field to an output field, click the circle next to the source element once, then click the circle next to the target element. A line will be drawn between the two, indicating a mapping from the source to the target.  tutorial html c7529b39125204de

  10. Click X to close the map editor. Your assembly policy for the shipping.calc operation is now complete.

    tutorial html 60e39f1d04c62b0b
  11. Save your changes.

    tutorial html 8eaea845d79feb97

Use GatewayScript in an Assembly

In this section, you will configure the assembly for the store locator resource. You will use GatewayScript to modify the response to your consumers, providing them a maps link to the nearest store location.

Configure the get.stores Case

This operation will call out to the Google Geocode API to obtain location information about the provided zip code, and will then utilize a simple gatewayscript to modify the response and provide a formatted Google Maps link.

  1. Add an invoke policy to the [[get.stores case]].   tutorial html 8fcccda10f7fbc1e

  2. Edit the new [[invoke action]] with the following properties:

    • [[Title: invoke_google_geolocate  ]]

    • [[URL:]]

    • [[Stop on error: unchecked ]]

    • [[Response object variable (scroll to the bottom): google_geocode_response]]   tutorial html c230669eaa51ffee      tutorial html bcc946b43e8188

  3. Click [[X]] to close the invoke editor.

  4. Add a [[gatewayscript policy]] with the following properties:

    • [Title: gws_format_maps_link]

    • Copy the following GatewayScript snippet and paste it into the text area:

// Save the Google Geocode response body to variable
var mapsApiRsp = apim.getvariable('google_geocode_response.body');
// Get location attributes from geocode response body
var location = mapsApiRsp.results[0].geometry.location;
// Set up the response data object, concat the latitude and longitude
var rspObj = {"google_maps_link": "" + + "," + location.lng};

tutorial html d005e2f600ea91f1

  • [Note: Take a quick look at line 5. Notice how our gateway script file is reading the body portion of the google_geocode_response variable which was assigned to the output of the invoke action.]

    Click [[X]] to close the gatewayscript editor.

    Your assembly for the `logistics` API will now include two separate operation policies:  

    tutorial html 3e32e5d9e2c3d543
  1. Save your changes.   tutorial html 8eaea845d79feb97

  2. Click [[Develop]] in the navigation menu to return to the list of APIs and Products in your system.

    tutorial html a810481f55373ff0


Congratulations! You have successfully configured two new API’s with advanced assemblies. Throughout the tutorial, you explored the key takeaways:

  • Create a new API, including object definitions and paths.

  • Configure an API to access an existing SOAP service.

  • Import an existing API from an OpenAPI definition document (a.k.a Swagger).

  • Map data retrieved from multiple API calls into an aggregate response.

  • Use GatewayScript directly within an API assembly.

Continue with the APIC Dev Jam! Go to APIC Dev Jam - Lab 6 - Working with API Products)] to learn about bundling the API’s into a Product and publishing it to the consumer portal.