Application shared subscriptions management

The Application Shared Subscription entity enables the Shared Subscriptions feature for APPLICATION clients. Multiple clients can subscribe to a shared topic filter and receive messages in a round-robin fashion. When an entity is created, a corresponding Kafka topic is automatically provisioned to store its messages.

Creating or managing Application Shared Subscription entities requires an authenticated admin user.

All examples below use curl. Replace localhost:8083 with your server address if TBMQ is running remotely.

Authentication

Obtain an access token by logging in:

curl --location --request POST 'http://localhost:8083/api/auth/login' \
--header 'Content-Type: application/json' \
--data-raw '{
    "username":"[email protected]",
    "password":"sysadmin"
}'

The response contains a token field. Export it for use in subsequent requests:

export ACCESS_TOKEN=PLACE_YOUR_TOKEN_HERE

Create or update an Application Shared Subscription

curl --location --request POST 'http://localhost:8083/api/app/shared/subs' \
--header "X-Authorization: Bearer $ACCESS_TOKEN" \
--header 'Content-Type: application/json' \
--data-raw '{
    "name": "test",
    "partitions": 1,
    "topicFilter": "test/topic"
}'

This creates an entity in PostgreSQL and a Kafka topic named tbmq.msg.app.shared.test.topic with one partition.

Kafka topic naming convention

TBMQ maps the MQTT topic filter to a Kafka topic name using the following rules:

Rule	Example
Prefix `tbmq.msg.app.shared.` is added	—
`/` → `.`	`test/topic` → `tbmq.msg.app.shared.test.topic`
`#` → `mlw` (multi-level wildcard)	`test/#` → `tbmq.msg.app.shared.test.mlw`
`+` → `slw` (single-level wildcard)	`test/+` → `tbmq.msg.app.shared.test.slw`

If the topic filter contains characters outside alphanumeric, /, #, and +, a hash of the filter is used:

tbmq.msg.app.shared.$TOPIC_FILTER_HASH

This behavior is controlled by TB_APP_PERSISTED_MSG_SHARED_TOPIC_VALIDATION (enabled by default). Disabling it means Kafka topics will not be created for topic filters with special characters.

Get all Application Shared Subscriptions

curl --location --request GET 'http://localhost:8083/api/app/shared/subs?pageSize=100&page=0' \
--header "X-Authorization: Bearer $ACCESS_TOKEN"

pageSize=100 and page=0 returns the first 100 entities.

Delete an Application Shared Subscription

Deleting the entity also deletes the associated Kafka topic.

curl --location --request DELETE 'http://localhost:8083/api/app/shared/subs/$APP_SHARED_SUBS_ID' \
--header "X-Authorization: Bearer $ACCESS_TOKEN"

Replace $APP_SHARED_SUBS_ID with the actual ID of the entity to delete.