APIC Dev Jam Lab 5 - Advanced API Assembly

• 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

Create and Define the Financing API (REST to SOAP)

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

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

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

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

Click **Next**.
Copy to clipboardCopied!

5. 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.

   

6.  Click  [Edit API ]to customize the API.**

7. 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.

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

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

   

10. Edit the property values using the following values:

The property will be utilized in the Path you create next.
Click **[Save]** to go back to the main API
Editor.
Copy to clipboardCopied!

11. Click [[Paths]] in the navigation menu on the left. Then click [Add] to create a new path.

    

12. 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.]**

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

    

14. From the [Add Operation] menu, select the [Get] operation and then click [Add]. 

    

15. Click [Save]. You will be redirected to the main API Editor to continue.

    

16. Click the [/calculate] path we just created.

    

17. 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.

    

18. 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.

    

19. 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

Copy to clipboardCopied!

20. 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]]

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

    

Map the API to a Service WSDL

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.

   

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

   

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

   Build the Financing API Assembly

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

   

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

   

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

   

9. Now you are going to modify the input and output map policy for mapping your REST API into SOAP.

   

10. 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.

    

11. Scroll down to map and insert [[version: 2.0.0]] right below it. 

    

12. Scroll down to invoke and insert [[version 2.0.0]] right below it. Skip if the version 2.0.0 is already populated.

    

13. 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.

    

14. 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.

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

    

11. Click [[+ parameters for operation...]] and select the [GET Calculate operation].

    

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

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

14. Click [[`X`]] in the map editor to return to the policy pipeline.

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

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

    

17. Click [[`X`]] to return to the policy pipeline.

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

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

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

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

    

22. 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.

    

23. Click [[`X`]] in the map editor to return to the policy pipeline.

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

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

    

Import Logistics API

Import the OpenAPI Definition

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

   

2. From the Create API wizard, select [[Import: Existing OpenAPI]]. Then click [[Next]].  

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.

   

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]].

   

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

   

Create an Orchestration Assembly

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:

   

Configure the shipping.calc Case

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]]      

   • [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:  

    

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]]  

     

5. Add a [[map policy]] after the last invoke and then click it to open the editor.    

6. 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]]

7. 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]]

8. You now have two inputs assigned to the map policy:  

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

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

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

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

13. 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. 

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

    

15. Save your changes.

    

Use GatewayScript in an Assembly

Configure the get.stores Case

1. Add an invoke policy to the [[get.stores case]].  

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

   • [[Title: invoke_google_geolocate  ]]

   • [[URL: https://maps.googleapis.com/maps/api/geocode/json?&address=]]

   • [[Stop on error: unchecked ]]

   • [[Response object variable (scroll to the bottom): google_geocode_response]]       

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": "https://www.google.com/maps?q=" + location.lat + "," + location.lng};

Copy to clipboardCopied!

• [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:  

  

7. Save your changes.  

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

   

Summary

• 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.