Using AMQP (MQ Light API) in the IBM Message Hub Incubator

Share this post:

icon32x32-incubator Following on from Adrian’s post on the Message Hub Incubator, this tutorial is about the first feature that we are developing, the MQ Light API.

This tutorial shows how to deploy a Node.js messaging app using the Message Hub Incubator Bluemix service and its MQ Light API. After following it you’ll understand how the service works, see the benefits of worker offload, and be able to get started developing your own applications.

Why use the MQ Light API?

The MQ Light API provides a simple but powerful AMQP-based messaging API which can used on a standalone machine, as part of an on-premise enterprise messaging solution or in the cloud.

By using the API to connect to the Message Hub Incubator service in Bluemix, applications can take advantage of the highly scalable, high throughput, secure cloud messaging bus that Message Hub provides, simplifying connecting on and off-premise applications as well as providing easy access to streaming services such as analytics.

The MQ Light API is currently available in Java, Node.js and Ruby. They all work in a similar way, but here we’ll use Node.js.

What does the sample do?

The sample app is actually composed of two simple apps which work together:

  • MQL.fishalive.node.frontend – A web front-end where a user types in a sentence to be capitalized. The app breaks the sentence down into words which are sent to the back-end application below as a series of messages for processing.
  • MQL.fishalive.node.backend – The back-end processing application receives the words from the front-end, capitalizes them and sends them back. Any number of the back-end application can be run according to the processing capacity required.


Although the work performed by the sample is trivial, it demonstrates:

  • How easy it is to get disjoint apps talking to each other using the MQ Light Service. The apps could just as easily be running outside of Bluemix either on a local server or another cloud.
  • The simplicity of using the MQ Light API to perform worker offload, a classic messaging scenario, where a front end app which needs to stay responsive to users offloads intensive operations to a back-end app which can be seamlessly scaled up or down as needed.

Get the sample code and deploy it


Complete the following steps:

Download the sample

The sample source code is available in GitHub. To download, clone the repository for the language you want to use. For Node.js:

git clone

(To try out the Java or Ruby samples substitute ‘node’ in the URL above with either ‘java’ or ‘ruby’).

Deploying to Bluemix

To create an instance of the Message Hub Incubator service for the sample to use, run the following Cloud Foundry command:

cf cs MessageHubIncubator experimental MQLight-sampleservice

This creates an instance of the MessageHubIncubator service, named MQLight-sampleservice, using the experimental (free) payment plan. Services can also be created using the Bluemix WebGUI console by selecting ‘Catalog’ from the main menu and clicking on the tile for the service.

Tip: The service can be given any name, however the two ‘services’ fields in the sample’s manifest.yml file must be updated to match. This ensures that when the sample apps are deployed they are bound to the correct service.

To deploy the sample to Bluemix, run the cf push command from the directory where the sample was cloned. The manifest.yml file in this directory contains the information needed by Bluemix to deploy the sample. The manifest.yml file is optional, but it avoids having to specify all the arguments each time you run the command. For a full list of options, run the command cf push -h.

Once the apps finish deploying, you can use the command cf apps to check their status (or take a look at them in the Bluemix dashboard).

To try the sample, copy the URL listed for the front-end app in to a browser. You’ll see something similar to the screenshot shown at the start of the tutorial.

Clicking ‘Submit work’ triggers the front-end app to divide the given sentence into words and publish them as messages to a topic called mqlight/sample/words.

The back-end worker apps are subscribed to this topic and on receiving each message, capitalizise it and return it using the topic mqlight/sample/wordsuppercase/. As each back-end worker app is subscribed to the same topic, to ensure each message is only received by one of them the sample uses a feature of the MQ Light API called a ‘shared destination’. This ensures messages are distributed fairly between all subscribing applications rather each receiving its own copy of every message.

The front-end application is subscribed to the topic mqlight/sample/wordsuppercase/ and displays each word as it’s returned.

In a real-world scenario, if more processing power was required, the capacity of the back-end app could be changed by changing the number of back-end instances. For example, to scale out to 5 instances, run the command cf scale MQL.sample.node.backend -i 5. That’s it! You’ve deployed the samples, used the Incubator service to allow them to communicate and experimented with the principals of worker offload.

Learn More

If you’d like to understand more about how the samples used the MQ Light API to achieve the above, take a look at the app.js files in the frontend and backend directories at the location the sample was cloned.

To find out more about the Message Hub Incubator service and its latest features, see IBM Message Hub Incubator overview and get started with it in the Bluemix Catalog. Or try the full Message Hub service in the catalog.

More How-tos stories
May 3, 2019

Kubernetes Tutorials: 5 Ways to Get You Building Fast

Ready to start working with Kubernetes? Want to build your Kubernetes skills? The five tutorials in this post will teach you everything you need to know about how to manage your containerized apps with Kubernetes.

Continue reading

May 3, 2019

Using Portworx to Deploy and Manage an HA MySQL Cluster on IBM Cloud Kubernetes Service

This tutorial is a walkthrough of the steps involved in deploying and managing a highly available MySQL cluster on IBM Cloud Kubernetes Service.

Continue reading

May 2, 2019

Kubernetes v1.14.1 Now Available in IBM Cloud Kubernetes Service

We are excited to announce the availability of Kubernetes v1.14.1 for your clusters that are running in IBM Cloud Kubernetes Service. IBM Cloud Kubernetes Service continues to be the first public managed Kubernetes service to support the latest upstream versions from the community.

Continue reading