Restful HTTP APIs With HiveMQ
Written by The HiveMQ Team
Published: May 2, 2016
These days no enterprise software is complete without providing a way to integrate with other components in a software landscape. While MQTT is an awesome way to integrate backend systems, often this will be achieved by using HTTP-APIs, sometimes also called “Webservices”.
Of course, with HiveMQ the integration into other systems can be done purely in Java using the open source plugin system. HiveMQ also provides a RestService which allows you to create a custom HTTP-API or even a REST-API which can be consumed by other applications.
This blog post will give an introduction into the latter one and show you how you can add a HTTP-API to HiveMQ with only a few lines of code.
Plugin developers can utilize HiveMQs RestService for creating accessible HTTP APIs directly within HiveMQ. If you are getting started with HiveMQ plugins and plugin services, take a look at the Plugin Developer Guide to get a jumpstart with HiveMQ plugins.
The RestService enables you to serve HTTP content directly from HiveMQ, namely:
- Multiple HTTP endpoints
- JAX-RS based HTTP/REST-APIs
- Servlets and ServletFilters
But HiveMQ not only gives a plugin developer a simple way to add such APIs, it also makes all other plugin services available for the use within these APIs. In the following example code these services are used to get the subscriptions of all currently known MQTT clients. There is a lot more you can do with those services, see the Plugin Developer Guide for a list of those services.
HiveMQ can serve different HTTP endpoints called listeners. These listeners can be added to HiveMQ either by configuring them in HiveMQ’s config file or by declaring them programatically.
You can serve different content on different listeners or on all available listeners. You can even serve some content on a specific listener and some other content on all listeners.
Example HiveMQ configuration file with HTTP listener on port 8080:
Adding a listener on all interfaces with port 8888 programatically:
restService.addListener(new HttpListener("listener-name", "0.0.0.0", 8888));
By default HiveMQ will serve JAX-RS Applications or JAX-RS Resources with the root path
/ and serve Servlets under the root path
HiveMQ utilizes the JAX-RS API to provide a simple and well-known principle for implementing Webservices with Java. The easiest way to create such a service is to create a JAX-RS Resource and make it known to the RESTService.
Adding a Resource to the RESTService:
Example API implementation:
These few lines of code now create a HTTP API endpoint at
http://broker-ip:8080/example/subscriptions/ which will return a JSON response containing a list of clients and their subscriptions on a HTTP GET request.
HiveMQ’s RESTService can also serve Servlets directly from HiveMQ. An example Servlet which serves a HTML page with a list of all connected MQTT clients would look like this.
It can be added to RESTService by calling:
It can then be viewed in the browser at the URL
HiveMQ’s plugin services also offer an async API for every service so it makes a lot of sense to also serve a HTTP-API in an async fashion. By using the async APIs you get better scalability and the general resource consumption of your plugin will also be lower than using the blocking APIs.
To show how the async APIs can be used together with JAX-RS the following is implementing the same example in an asychronous way.
JAX-RS example with async API:
Of course HiveMQ supports the current Servlet 3.0 API which provides asynchronous execution of a request.
Servlet example with async API:
For more example code there is a rest-example-plugin which contains the blocking as well as the asynchronous examples and and shows how to add subscriptions via HTTP-API.
The example project is available on Github.
HTTP-APIs are a good and well-known way to integrate different software systems, especially if these systems do not support MQTT (yet). With the RESTService, HiveMQ provides an easy option for everyone who need their MQTT broker to communicate with other backend systems that don’t support MQTT in just a few lines of code while still providing scalability in a non-blocking fashion.