[APIC]Connect back-end systems to APIs with IBM API Connect and IBM MQ

http://www.ibm.com/developerworks/library/mw-1611-hutchinson-trs/index.html

Connect back-end systems to APIs with IBM API Connect and IBM MQ

Custom policy captures IBM DataPower and MQ functions to create public-facing APIs

Charlotte Hutchinson, Chris Phillips, and Jack Dunleavy
Published on November 28, 2016

FacebookTwitterLinked InGoogle+E-mail this page

Integration between IBM® API Connect and IBM MQ is vital for reliable messaging. Until now, this integration has not been available for environments that use back-end systems to communicate through MQ. Thanks to a new custom policy for API Connect to integrate with IBM MQ, you can seamlessly create public-facing APIs to work with your back-end systems. This custom policy captures the existing compatibility of IBM DataPower® and MQ.

This tutorial explains how you can use a custom policy that we developed to integrate an instance of API Connect with an MQ queue manager. With this policy, APIs that are managed by API Connect can target MQ queues. The API layer can readily interact with back-end systems that are exposed by using IBM MQ. In this process, when the API is called, API Connect produces a SOAP envelope and publishes the SOAP envelope to the MQ queue.

Before you complete this tutorial, you must have a general understanding of API Connect. You must also have an IBM DataPower Gateway as the API run time and an MQ queue manager that is accessible to the IBM DataPower Gateway.

Policies in API Connect

More on policies
Policies are stored on a per-catalog level, meaning that, if a policy is required in more than one catalog, you must import it into each catalog separately.

By using the API Connect assembly tool, you can add transformations and logic to the runtime behavior of your APIs. You can use the assembly to create complicated flows that feature logical constructs, such as if and switch statements. You can also create data manipulation mechanisms, such as field redaction, JSON-to-XML, and input-to-output mapping. These actions are called policies. You can connect and organize them by dragging the tiles to the assembly.

API Connect provides a way to take an API request and then start one or more HTTP services. However, we want the API request to start an MQ SOAP service instead of an HTTP service. The following steps explain how this solution works:

1. A consumer calls an API by using HTTPS.
2. The SOAP message is created with information from the initial API request.
3. The SOAP message is put on the request queue.
4. The MQ service gets the message from the request queue and puts a response on the reply queue.
5. The MQInvoke policy gets the response from the queue.
6. If no reply queue is specified, it returns the MQMD headers.

The following figure illustrates the steps in this solution. The SOAP message can be constructed by using the Mapping policy in API Connect or by creating a SOAP Envelope Generator user-defined policy.

MQInvoke user-defined policy

To address the identified challenges in integration with API Connect and MQ, you can use a user-defined policy. In this tutorial, we use and describe the MQInvoke policy, which you can download from GitHub.

You define the MQInvoke policy by using the following parameters in the configuration panel for this policy:

• Queuemanager. Set this variable to the name value for the IBM MQ Queue Manager Object or IBM MQ Queue Manager Group Object in IBM DataPower.
• Queue. Set this variable to the name of the request queue within the queue manager that you selected.
• Replyqueue. Set this variable to the name of the reply queue within the queue manager that you selected. If the message flow is not intended to be synchronous, leave this value as null or " ".
• Backoutq. If needed, set this variable to the name of the backout queue within the queue manager that you selected. If you set the Replyqueue to null or " ", the policy does not place bad messages onto the backout queue. You must define the backout queue here and not in the DataPower MQ object.
• Timeout. Enter the time, in milliseconds, after which the policy will declare the queue manager unreachable, returning a 408 timeout reached response code.

When the user-defined profile is started, it places the current message body into the specified Request Queue on the queue manager that is registered in DataPower (QM object). If the Reply Queue is empty, this request is a one-way request. Otherwise, the request is synchronous. For a synchronous request, a response is expected on the reply queue name. The reply queue is polled until a message with a CorrelId that matches the request is received. The body from the response message is sent back to the API consumer. For a one-way request when the message is put on the MQ queue, a response is returned to the API consumers.

1

Create the DataPower extension

To create the DataPower extension, log in to IBM DataPower.

1a

Create a domain

Create a domain where you will develop the DataPower extension and user-defined policy. This domain is just for creating the MQ objects; you can remove it afterward.

1. In the Search field, type domain.
2. From the results, click Application Domain.
3. In the Application Domain pane, click New.
4. For Name, type MQ.
5. Click Apply.

   View image at full size

6. Save the configuration.
7. Click the current domain in the upper-right corner, and select the MQ domain.

1b

Add the queue manager objects

1. In the Search field, type Queue.
2. From the options under the Search field, click IBM MQ Queue Manager.
3. Click New.
4. Enter the following properties. In this example, we use the values that are shown. Your own values might vary.
   1. For Name, enter QM1.
   2. Enter your host name in the format xxx.xxx.xxx.xx:xxxx.
   3. For Queue Manager Name, enter QM1.
   4. For User Name, enter dpuser.
   5. Click the plus sign (+) for XML Manager.
   
5. In the Configure user agent window, for Name, enter MQUserAgent.
6. Click Apply.

   View image at full size

7. Save the configuration.

1c

Add the DataPower extensions

A DataPower extension requires you to create a control file under the local://ext/ directory to specify its behavior. In this scenario, we use DataPower extensions as a mechanism to deploy objects that are required for a user-defined policy. Therefore, the extension file does not require any content aside from the required extension tag.

To add the DataPower extensions:

1. Open a text editor.
2. Add the following lines:
   <extensions>
</extensions>
3. Save the file with the name extensions.xml.
4. Within File Management, for the local folder, click the Actions link, and click Create Subdirectory.
5. Type ext and click Confirm Create.
6. Click Actions. Select Upload Files, and locate the extensions.xml file that you just created.

The following figure shows the extension file that we created.

1d

Export the configuration

1. From the options under the Search field, click Export Configuration.
2. Select Export data for select configurations from the current domain, and click Next.
3. In the Export Configuration window, complete the following settings:
   1. For File name, enter mqextension.
   2. In the Available objects box, select IBM MQ Queue Manager Group, and click the right arrow (>) to move the selection to the Selected Objects box.
4. Click Download.

Now, you can add the compressed extension file that you downloaded as a DataPower service extension in the Cloud Manager as explained in the following step.

2

Add the extension to API Connect

1. Log in to the Cloud Manager.
2. Click Services.
3. Scroll down to the DataPower Services, and in the Gateway section, click the Configuration icon.
4. In the configuration window, scroll down to the API Gateway Extension, and click Browse.
5. Locate the compressed extension file that you downloaded.
6. Click Save.

While the extension is being added, you see a REFRESH message that is displayed for several minutes. After the extension is added, you see a message of ACTIVE.

3

Import the policies to API Connect

1. To use the policies, import the compressed file into API Connect. After you import it, the policy is displayed in the assembly, as shown at the bottom of the following figure, and is ready for use.
2. Drag the policy to the assembly as many times as required. Each instance of the tile holds its own, distinct configuration.
3. To configure the MQInvoke policy, enter the details of the MQ instance that you have running:
   1. For queuemanager, enter MQDAC01.
   2. For queue, enter API1IN.
   3. For replyque, enter API1OUT.
   4. For backoutq, enter API1OUT.
4. Test the API.

Enabling SSL between DataPower and MQ for security

When you connect DataPower to an MQ system, use a Secure Sockets Layer (SSL). For security reasons, when exporting DataPower configuration, the cryptographic material is omitted. Therefore, you must handle the SSL in a slightly different manner:

1. Create a Transport Layer Security (TLS) profile in the API Connect Cloud Manager.
2. Place the Trust Store and Presenter certificates as required.
3. When you create the MQ object as detailed in the previous section, set the SSL Client Profile to the TLS profile that you created.

The DataPower extension that is included contains a reference to a TLS profile that is configured in the API Connect Cloud Manager. If for any reason this TLS profile needs adjusting, you can view the profile in the Cloud Manager under TLS Profiles.

Conclusion

This tutorial explained a versatile solution to help you address the challenges of integrating API Connect and MQ. By using the user-defined policy as described, you can call an API, put this SOAP envelope on a request queue, start the MQ service, and parse back the body of the SOAP response.

Acknowledgments

The authors thank Natasha Kirkup, Callum Jackson, Aiden Gallagher, Timothy Quigly, and Mark Ellerington for their continued support and insight during development of the custom policy.

Downloadable resources

• PDF of this content

Related topics

• IBM API Connect developer center
• /api Explorer developer center
• IBM DataPower Gateways developer center
• The assemble view
• Including components in your assembly