HiveMQ Edge REST API

HiveMQ Edge can be optionally configured to expose an administrative API and an administrative user interface. The admin user interface uses the API to fulfill all of its features.

HiveMQ Edge REST API Configuration

HiveMQ Edge is designed to use sensible default values. When you run the default HiveMQ Edge configuration, the HiveMQ Edge API web server and user interface start up with a listener bound to port 8080.

HiveMQ Edge default API configuration

<?xml version="1.0"?>
<hivemq xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <admin-api>
        <enabled>true</enabled>
    </admin-api>
</hivemq>

Example configuration to change the HiveMQ Edge API listener address and port

<?xml version="1.0"?>
<hivemq xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <admin-api>
        <listeners>
            <http-listener>
                <port>80</port>
                <bind-address>0.0.0.0</bind-address>
            </http-listener>
        </listeners>
    </admin-api>
</hivemq>

HiveMQ Edge API and User Interface Authentication

The HiveMQ Edge API is secured using a Bearer Token scheme. This authentication method involves presenting an HTTP header with the following format in all requests for secured resources:

Authorization : "Bearer <JWT>"

The JWT (JSON Web Token) is generated by calling the API endpoint:

POST  /api/v1/auth/authenticate

Username and password credentials that match an entity in your configuration XML should be posted to the endpoint. If the credentials are valid, the webservice returns a JWT that can be used to secure future requests. To add, remove, or modify the users who are allowed access to the API and user interface, edit the users element in your config.xml file.

Changing API Users

<?xml version="1.0"?>
<hivemq xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <admin-api>
        <users>
            <user>
                <username>admin</username>
                <password>hivemq</password>
                <roles>
                    <role>admin</role>
                </roles>
            </user>
        </users>
    </admin-api>
</hivemq>

By default, the JWTs the authenticate endpoint issues expire after 30 minutes. You can change the expiry, and other parameters of the generated token in the API configuration XML file.

Example cURL command to request a JWT from localhost:8080

curl 'http://localhost:8080/api/v1/auth/authenticate' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  --data-raw '{"password":"hivemq","userName":"admin"}' \
  | jq .token -r

Example configuration to change the generated JWT

<?xml version="1.0"?>
<hivemq xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <admin-api>
        <generated-tokens>
            <keySize>2048</keySize>
            <issuer>HiveMQ-Edge</issuer>
            <audience>HiveMQ-Edge-Api</audience>
            <expiryTimeMinutes>30</expiryTimeMinutes>
            <tokenEarlyEpochThresholdMinutes>2</tokenEarlyEpochThresholdMinutes>
        </generated-tokens>
    </admin-api>
</hivemq>

Example configuration to add secure TLS to API

<?xml version="1.0"?>
<hivemq xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <admin-api>
        <listeners>
            <https-listener>
                <port>443</port>
                <bind-address>127.0.0.1</bind-address>
                <tls>
                    <protocols>
                        <protocol>TLSv1.2</protocol>
                    </protocols>
                    <cipher-suites>
                        <cipher-suite>TLS_RSA_WITH_AES_128_CBC_SHA</cipher-suite>
                        <cipher-suite>TLS_RSA_WITH_AES_256_CBC_SHA256</cipher-suite>
                        <cipher-suite>SSL_RSA_WITH_3DES_EDE_CBC_SHA</cipher-suite>
                    </cipher-suites>
                </tls>
            </https-listener>
        </listeners>
    </admin-api>
</hivemq>

Table 1. Available TLS parameters
Name	Default	Mandatory	Description
`protocols`	`All enabled`	`no`	The enabled protocols. Possible entries are `TLSv1.2`, `TLSv1.1`, and `TLSv1`.
`cipher-suites`	`All cipher suites enabled`	`no`	The enabled cipher suites. If desired, define specific cipher suites to limit the number of suites that are enabled. NOTE: The available cipher suits are dependent on the SSL implementation that is used and not necessarily the same for all machines.
`keystore.path`	`none`	`yes`	The path to the key store where your certificate and private key are located.
`keystore.password`	`none`	`yes`	The password to open the key store.
`keystore.private-key-password`	`none`	`no`	The password for the private key (if applicable).

Using The HiveMQ Edge API

The HiveMQ Edge API is generated from JAX-RS compliant web service definitions based on the OpenAPI specification. The latest version of the specification document can be generated from the source repository using the supplied gradle task:

./gradlew :openApiSpec

You can also refer to the version-controlled HiveMQ Edge Open API document.

The HiveMQ Edge API provides functionality to control the addition, removal, modification, and runtime control of MQTT bridges and protocol adapters. The API also gives you the ability to set up and modify Unified Namespace (UNS) configurations.

For a list of all the available services, see HiveMQ Edge Open API.