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 and secure HTTPS.

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.

HiveMQ REST API Configuration

The HiveMQ REST API uses sensible default settings. Unless otherwise configured, the REST API bind address is 127.0.0.1 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>
    <!-- Enables or disables the HiveMQ REST API-->
    <enabled>false</enabled>
    <!-- Enables or disables authentication and authorization for the HiveMQ REST API-->
    <auth>
        <enabled>false</enabled>
    </auth>
    <listeners>
        <http>
            <port>8888</port>
            <bind-address>127.0.0.1</bind-address>
            <!-- Defines listener name to help distinguish between multiple listeners -->
            <name>your-http-listener</name>
        </http>

    </listeners>
 </rest-api>
 ...
</hivemq>

Configuration Default Value Description

rest-api

false

Enables or disables the use of the HiveMQ REST API. The HiveMQ REST API is disabled by default.

enabled:When the enabled option is set to false, no users or extension developers can use the HiveMQ REST API. To allow access to the API, set the enabled tag to true.

auth

false

Enables or disables user authentication and authorizations for the HiveMQ REST API. User authentication and authorization for the HiveMQ REST API is disabled by default.

enabled: When the enabled option in the auth tag is set to true, HiveMQ applies your configured authorization and authentication mechanisms to restrict access to the HiveMQ REST API as defined.

Authentication and authorization for the REST API requires additional configuration with the HiveMQ Enterprise Security Extension or use of the HiveMQ Enterprise Extension SDK. For more information, see HiveMQ Enterprise Security Extension REST APi Access Control and HiveMQ Enterprise SDK REST Service.

listeners

Configures one or more http or https listeners to provide access to the HiveMQ REST API.

port:The port on the local machine that listens for HiveMQ REST API requests. The default port for HTTP listeners is 8888. The port address can be changed.
bind-address: The address on the local machine that accepts HiveMQ REST API requests. The default bind address is 127.0.0.1. The bind address can be changed.
name: Optional setting to define a name for the listener. Custom-defined listener names can be helpful when multiple listeners are in use. If no name is specified, HiveMQ uses the type of listener plus the port. For example, http-listener-8888.

REST API Listeners

The HiveMQ REST API provides flexible configuration options that allow you to use one or more listeners with different protocols and bind addresses.

HTTP Listener

The default HiveMQ REST API configuration uses a standard HTTP listener.

Example HTTP listener configuration for the HiveMQ REST API

     <listeners>
         <http>
             <port>8888</port>
             <bind-address>127.0.0.1 </bind-address>
         </http>

        <!-- Optional setting to define the name of the listener  -->
        <!--
        <name>your-http-listener</name>
        -->

     </listeners>

HTTPS Listener

To enforce secure TLS encrypted communication, you can configure a HTTPS listener to connect to the HiveMQ REST API.

Example secure HTTPS listener configuration for the HiveMQ REST API

    <listeners>
        <https>
            <port>8443</port>
            <bind-address>0.0.0.0</bind-address>
            <tls>
                <keystore>
                    <!-- The path to the key store -->
                    <path>/path/to/key/store/store.jks</path>
                    <!-- The password of the key store -->
                    <password>changeme</password>
                    <!-- The password of the private key -->
                    <private-key-password>changeme</private-key-password>
                </keystore>

                <!-- Optional setting to explicitly define the accepted TLS version  -->
                <!---
                <protocols>
                    <protocol>TLSv1.3</protocol>
                </protocols>
                -->

                <!-- Optional setting to explicitly define the accepted cipher suites -->
		        <!--
                <cipher-suites>
                        <cipher-suite>TLS_RSA_WITH_AES_256_CBC_SHA256</cipher-suite>
                        <cipher-suite>TLS_RSA_WITH_AES_256_GCM_SHA384</cipher-suite>
                </cipher-suites>
                -->

                <!-- Optional setting to define the name of the listener  -->
                 <!--
                <name>your-https-listener</name>
-                -->

            </tls>
        </https>

    </listeners>

The HiveMQ REST API supports TLSv1.2 and TLSv1.3 only. If the configured TLS maximum value for a client is lower than TLSv1.2, the client cannot connect to the HiveMQ REST API and a protocol version error is logged. Similarly, if you explicitly define that the REST API only accepts TLSv1.3 connections, clients that do not support TLSv1.3 cannot connect to the HiveMQ REST API and a protocol version error is logged.

Table 2. HTTPS Listener Configuration Options
Parameter	Default	Description
`port`	`8888`	The port on the local machine that listens for HiveMQ REST API requests. The HTTPS `port` address can be changed.
`bind-address`	`127.0.0.1`	The address on the local machine that accepts HiveMQ REST API requests. The HTTPS `bind-address` can be changed.
`path`		Location of the P12 or JKS certificates that the keystore uses to store entries.
`password`		The password to the associated keystore.
`private-key-password`		The password that protects the private key of the keystore.
`protocol`		Optional setting to manually specify the versions of the TLS protocol that can be used to secure communication to the HiveMQ REST API. For example, you can configure the REST API to only accept TLSv1.2. By default, the HiveMQ REST API uses the default TLS version of your JDK.
`cipher-suite`		Optional setting to explicitly define cipher suites. If desired, you can define specific cipher suites to limit the number of suites that are enabled. If no cipher suites are specified in the `cipher-suites` tag or the tag is missing, the REST API uses the default cipher suites of your JDK .
`name`		Optional setting to define a name for the listener. Custom-defined listener names can be helpful when multiple listeners are in use. If no name is specified, HiveMQ uses the type of listener plus the port. For example, `https-listener-8443`.

Make sure the port you configure for your HTTPS listener is not already in use by any other service.

HiveMQ 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.