API Connect

Objective

In this tutorial, you will learn:

• How to author and package an IBM API Connect Custom Policy (User-Defined Policy) on IBM DataPower to extend behaviors for APIs.
• How to create an API, configure the Custom Policy (User-Defined Policy), stage, and publish the API.
• Create a catalog on APIC.

Create your Custom Policy (User-Defined Policy)

1. Open a browser and navigate to your DataPower web console: https://<Gateway_Appliance_URL>:9090 

2. Log into a sandbox domain of the appliance to create the artifacts required for the Custom Policy.

Create Subdirectories in File Management

3. Once logged in, navigate to the File Management, locate the local:// directory and click on Actions… > Create Subdirectory. Then create the folder policy. Create another subdirectory under policy named routing_cp.

4. Once the routing_cp directory is created, click on the Action… > Upload Files. Use the following XSL to create and upload routing_cp.xsl stylesheet to file management under routing_cp.

Notice: The code below may have been modified by the website (character encoding changed), therefore you may find the code in the completed custom policy zip linked in the pre-req section of this article.

<xsl:stylesheet
version=”1.0″
xmlns:xsl=”http://www.w3.org/1999/XSL/Transform”
xmlns:fo=”http://www.w3.org/1999/XSL/Format”
xmlns:xs=”http://www.w3.org/2001/XMLSchema”
xmlns:fn=”http://www.w3.org/2005/xpath-functions”
xmlns:dp=”http://www.datapower.com/extensions”
xmlns:dpconfig=”http://www.datapower.com/param/config”
xmlns:apim=”http://www.ibm.com/apimanagement”
extension-element-prefixes=”dp dpconfig apim”>

<!– Variables –>
<!– To use APIC extension functions the apim.custom stylesheet is included. –>
<xsl:import href=”local://isp/policy/apim.custom.xsl” />

<xsl:template match=”/”>
<!– Assigns the variable for the policy properties from the APIC custom policy. –>
<xsl:variable name=”vPolicyProperties” select=”apim:policyProperties()” />
<!– Assigns the variable for all the APIC context variables. –>
<xsl:variable name=”vAllContext” select=”dp:variable(‘var://context/_apimgmt/readContext’)” />
<!– Assigns the variable for all the query params. –>
<xsl:variable name=”vQueryParam” select=”apim:getContext(‘request.queryString’)” />
<!– Assigns the variable for the request parameter aeMultiPath. –>
<xsl:variable name=”vMultiPath” select=”apim:getContext(‘request.parameters.aeMultiPath’)” />
<!– Assigns the variable for the APIC Catalog. –>
<xsl:variable name=”vEnvironment” select=”apim:getContext(‘env.path’)” />

<!– Messages to syslogs when set to debug mode. –>
<xsl:message dp:priority=”debug”>Properties are: [<xsl:copy-of select=”$vPolicyProperties” />] </xsl:message>
<xsl:message dp:priority=”debug”>All APIC Contexts are: [<xsl:copy-of select=”$vAllContext” />] </xsl:message>
<xsl:message dp:priority=”debug”>Query Params are: [<xsl:copy-of select=”$vQueryParam” />] </xsl:message>
<xsl:message dp:priority=”debug”>MultiPath is: [<xsl:copy-of select=”$vMultiPath” />] </xsl:message>
<xsl:message dp:priority=”debug”>Catalog/Environment is: [<xsl:copy-of select=”$vEnvironment” />] </xsl:message>

<!– When user passes query param aeMultiPath=#, set the backend route to path#, otherwise return error statement to user.
When environment=’prod’, set request to path 3.–>
<xsl:choose>
<xsl:when test=”$vMultiPath = ‘1’”>
<dp:set-variable name=”‘var://service/routing-url'” value=”string($vPolicyProperties/path1)” />
</xsl:when>
<xsl:when test=”$vMultiPath = ‘2’”>
<dp:set-variable name=”‘var://service/routing-url'” value=”string($vPolicyProperties/path2)” />
</xsl:when>
<xsl:when test=”($vEnvironment = ‘prod’) or ($vMultiPath = ‘3’)”>
<dp:set-variable name=”‘var://service/routing-url'” value=”string($vPolicyProperties/path3)” />
</xsl:when>
<xsl:otherwise>
<dp:set-variable name=”‘var://service/routing-url'” value=”‘https://developer.ibm.com/apiconnect/'” />
</xsl:otherwise>
</xsl:choose>
</xsl:template>

</xsl:stylesheet>

Create Processing Rule

5. Navigate to the Processing Rule section of the webgui.

6. Click Add to add a new Processing Rule.

7. Specify the properties per the given table:

Create Processing Action

8. Add the Rule Action: Click on the (+) add new Rule Action icon and input the following properties into the Rule Action.

Once all values are set, Apply the Processing Action and Processing Rule, then Save Config.

Exporting and Downloading the Processing Rule from DataPower

9. Navigate back to the main Control Panel screen, locate and click the Export Configuration.

10. Click Next to continue with exporting the configuration

11. Select Processing Rule and select the routing_cp-main as shown in the figure below. Click on the greater than icon (>) to move the routing_cp-main over to the Selected Objects section.

12. Click Show Contexts to verify all the artifacts you’ll be exporting is correct, and click Next.
Note: you may see a warning message noting that the apim.custom.xsl referenced file is missing. This is ok. The file is located in the APIC generated domain, which we will have access to once the custom policy is uploaded.

13. Click Download to the configuration.

14. Rename the Export.zip to routing_cp.zip.

Packaging the DataPower Export and defining the policy for APIC

15. Create a folder Routing_CP and inside Routing_CP, create a sub-directory titled implementation.

16. Copy the routing_cp.zip into the implementation folder.

17. Create the routing_cp.yaml file shown below and copy the yaml file into the root of the Routing_CP directory where the implementation folder resides.

Notice: The code below may have been modified by the website (character encoding changed), therefore you may find the code in the completed custom policy zip linked in the pre-req section of this article.

This yaml file gives the policy its property inputs, which shall be used from the routing_cp.xsl stylesheet from the processing rule. The definition of the yaml file will define the policy as shown in the figure below:

18. Once the routing_cp.yaml file is completed, zip together the implementation and routing_cp.yaml.

Upload the Routing_CP.zip Custom Policy

19. Log into your IBM API Connect instance. https://<APIC_Management_URL>/apim 

20. Once logged in, expand the menu and pin the menu to lock it.

Ensure that you are in the designated Organization to create your API, it may not be the test org.

21. Click on the Dashboard from the left menu and in the main window, click on Sandbox.

22. In the Sandbox catalog, click the Settings tab, then the Policies sub-tab.

23. Click on the upload (

) icon to import the Routing_CP.zip custom policy. When the Import policy pops up, Browse… the Routing_CP.zip custom policy, and click Import.

Once the policy imports successfully, you will see the policy listed as shown in the following figure:

Create an API to use the Routing_CP Custom Policy

24. Click on Drafts from the left menu, select APIs in the main window, and click (+) Add to add a new API.

25. Name the new API route and click Next.

26. Ensure that the “Don’t add to a product” is selected on the Add a new API 2/2 window and click Add.

27. When the API Design opens, navigate down to the Paths section and in the main window click on the (

) add icon for the Paths section and a GET operation will be added automatically. Name the Path /route.

28. In the Paths section on the main window, click Add Parameter. Name the parameter aeMultiPath, and drop-down the Located in to select Query.

29. Click on the GET /route icon (

) to expand the operation and uncheck the Use API security definitions.

30. From the top of the main screen locate and click on Assemble tab. Then in the Assemble window, click on the DataPower Gateway policies radio button. Delete the Invoke policy in the assembly editor screen.

31. Locate the custom policy routing_cp, then drag and drop to the assembly editor flow.

31. Click on the routing_cp policy within the assembly editor flow and the policy configurations will slide out from the right.

33. Enter each Environment Endpoint to their corresponding path, as shown in the routing_cp custom policy figure below.

NOTICE: The front-side port 12329 may have been updated, please verify that one of the environment endpoints in the table are responding properly by testing http://<DataPower_Interface>:12329/BaggageService/Bags?id=1325.

Staging and Publishing an API

34. In the left menu navigator, click on Drafts and ensure you’re in the Products tab as shown in the figure.

35. Under the Products tab, click on the (+) Add to add a new Product.

36. When the Add a new product window pops up, enter Router for the name (casing does not matter). Click Add.

37. Once the Router product opens, locate and select the APIs section in the left nav, then in the main window, click on the (

) add icon in the APIs section to add an API.

38. Check to select the route API, and click Apply.

39. Back in the product window, click on the (

) Save icon to save the update.

40. Once saved, click on the (

) Staging icon to stage into the Sandbox catalog.

41.  Once staged, click on the Dashboard from the left menu navigator, then click on the Sandbox catalog in the main screen.

42. When the Sandbox catalog opens, locate the Router product and click the ellipsis (…) for the product and click on Publish.

43. Click on Publish in the Edit visibility and subscribers window.

Testing: Content Routing

44. After publishing, the API will be live and ready to be tested. Since this API contains a GET operation, we may directly invoke the API through a web browser with the appropriate query parameter.
Open a new browser tab and navigate to your catalogs base URL. Instructions on how to get the base URL is in the appendix titled Find your Catalogs Base URL.
Append the API path (/route) to the base URL and add the query parameter ?aeMultiPath=1 as shown in the figure below.

The request for QA would be as follows: https://<API_Endpoint_URL>/test/sb/route?aeMultiPath=2 

From the previous table, you can see that each path is routed to different backend endpoints. The takeaway from this example is that content based routing may be set up as a reusable custom policy to enrich and extend the functionality of your API.

Testing: Route by Catalog/Environment (PROD)

Before invoking the production based client-side URL to simulate prod, the prod catalog must be added. The following instructions will add the prod catalog and invoke the production based resource.

Create prod catalog

1. Navigate to the left menu slide out, click Dashboard. Then in the main window, click on (+) Add > Catalog to add a new catalog.

2. Enter prod for the Display Name and click Add.

3. Once completed, enter into the prod catalog.

4. Inside the prod catalog, click Settings tab on the top of the main window, and in the sub-tab Configuration, enable Sandbox as shown in the figure, and click the Save button on the top right have side.

5. Click on the sub-tab Policies and upload the Routing_CP.zip custom policy.

Stage and Publish from testing tool

Another way to stage and publish your API is through the testing tool from the Assemble editor in the API draft.

6. Click Drafts in the left navigator menu, then the API tab in the main window, and open the route API.

7. In the route API, click on the Assemble tab and click on the testing icon as shown in the figure:

8. If the testing tool shows the following, select Change setup, otherwise continue to the next step.

9. In the Setup section, choose prod for your Catalog, and ensure Router 1.0.0 is selected for your Product. Click Republish product and your API is live for the prod catalog.

Invoke prod API

By invoking the route API https://<API_Endpoint_URL>/test/prod/route itself, the custom policy will catch the prod catalog name scheme and redirect the request to its proper path 3 endpoint.

End Summary

In this tutorial, you

• Authored and packaged an IBM API Connect Custom Policy (User-Defined Policy) on IBM DataPower to extend behaviors for APIs.
• Created an API, configure the Custom Policy (User-Defined Policy), stage, and publish the API.
• Created a catalog and tested the custom policy.