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.

Add Comment
No Comments

Leave a Reply

Your email address will not be published.Required fields are marked *

More How-tos Stories

Using SSH tunnels and Selenium to test web applications on a continuous delivery pipeline

Developers often have a need to test their web applications. In particular they often have a need to automate these tests as part of a continuous integration (CI) pipeline. One such tool that helps facilitate this test requirement is Selenium. Selenium is a piece of software which is designed to automate browser behaviour, in that you can program it to visit a particular web page and then perform a series of actions on that web page. Most often this is leveraged to test web applications, although its functionality is not limited to that single use case. With a default configuration, however, this isn’t possible as the Selenium Server has no way of reaching an application that has been started within a CI container.

Continue reading

Integrate and Analyze Diagnostic Logs with IBM Cloud Log Analysis

Analyzing diagnostic logs, monitoring application health and keeping track of security-related events are at the foundation of successfully running apps and services. IBM Cloud offers services for that purpose. Today, I am going to show you how to use IBM Cloud Log Analysis to integrate, search and analyze as well as visualize diagnostic logs in the IBM Cloud.

Continue reading

Obey your commands: Home automation using Watson and PubNub

Integration of voice control in smart devices is buzzing, and adoption continues to grow. Voice control provides a more natural way of interacting with connected apps and devices ranging from news feeds, traffic information to acting as personal assistants in the home. These intelligent devices respond to commands spoken in our own voice and act immediately.

Continue reading