HiveMQ REST API

The HiveMQ REST API provides an interface for applications to interact programmatically with the HiveMQ Enterprise MQTT broker. Our REST API gives applications a way to send and receive data as JSON (JavaScript Object Notation) objects over standard HTTP.

HiveMQ administrators can use the REST API to automate Control Center actions they would normally perform manually. For example, start a trace recording every day at the same time, get a list of connected clients for further analysis, or initiate a backup process from a script.

The endpoints that the HiveMQ REST API offers fulfill many common use cases:

HiveMQ uses the versatile and widely supported OpenAPI Specification to create standard, machine-readable, programming-language agnostic interface descriptions for REST API.

The style of the HiveMQ REST API focuses on providing scalability and extensibility. The OpenAPI 3.0 schema definition of the HiveMQ REST API can be easily imported into popular API tools such as Postman or used to generate client-code in a wide array of programming languages. For more information, see API Style.

To view or download the complete HiveMQ REST API specification, see HiveMQ REST Specification.

Configuration

The HiveMQ REST API uses sensible default settings. Unless otherwise configured, the REST API bind address is localhost on port 8888.

By default, the HiveMQ REST API is disabled (<enabled>false</enabled>). When the REST API is disabled, no user or extension developer can access the API.

To enable the REST API, set the <enabled> option in the <rest-api> section of your HiveMQ configuration to true.

HiveMQ reads changes that you make to the conf.xml file of your HiveMQ instance during startup. To enable or disable the REST API, you must restart HiveMQ.

Example default HiveMQ REST API configuration

<?xml version="1.0"?>
<hivemq>
 ...
 <rest-api>
     <enabled>false</enabled>
     <listeners>
         <http>
             <port>8888</port>
             <bind-address>localhost</bind-address>
         </http>
     </listeners>
 </rest-api>
 ...
</hivemq>

Table 1. REST API Configuration Options
Configuration	Default Value	Description
`enabled`	`false`	Enables or disables the use of the HiveMQ REST API. When this option is set to `false`, no users or extension developers can use the HiveMQ REST API.
`port`	`8888`	The port on the local machine that listens for HiveMQ REST API requests. The `port` address can be changed.
`bind-address`	`localhost`	The address on the local machine that accepts HiveMQ REST API requests. The bind address can be changed.

You can configure multiple listeners at the same time with different ports and bind addresses.
For more information, see Listeners.

REST API Metrics

The HiveMQ REST API exposes numerous metrics that help you track and verify the performance of your application. API metrics provide useful information such as how long tasks take to execute, how frequently tasks are requested, and the percentage of total time spent on a transaction. Monitoring API metrics that are key to your use case with the monitoring solution of your choice allows you to respond to drops in application performance before your users experience problems.

For a complete list of all HiveMQ REST API metrics, see HiveMQ REST API Metrics.