Application Shared Subscription Entity

Authentication
Create/update Application Shared Subscription
Get all Application Shared Subscription entities
Delete Application Shared Subscription entity

The Application Shared Subscription entity provides the capability to leverage the Shared Subscriptions feature for APPLICATION clients. This feature enables multiple clients to subscribe and receive messages from a shared subscription. Upon creating the Application Shared Subscription entity, a corresponding Kafka topic is automatically created. This Kafka topic serves as a repository for all messages pertaining to the shared subscription.

To create a new Application Shared Subscription entity within the system, it is necessary to authenticate as an Admin user.

Authentication

To carry out administrative operations with the broker, it is imperative to log into the system and obtain an Access Token. This Access Token is essential for authenticating and authorizing your administrative actions.

To acquire the Access Token, you can execute the following command:

curl --location --request POST 'http://localhost:8083/api/auth/login' \
--header 'Content-Type: application/json' \
--data-raw '{
    "username":"sysadmin@thingsboard.org",
    "password":"sysadmin"
}'

Please be aware that if the broker is installed on a remote server, you must substitute “localhost” in the provided command with either the public IP address of the server or a designated domain name. Moreover, ensure that port 8083 is accessible publicly to establish the necessary connection. Additionally, remember to replace the “username” and “password” values in the command with the appropriate and valid credentials specific to your setup.

Upon successful authorization, the response will include a valuable piece of information known as the token. It is crucial to utilize this token for all subsequent administrative requests to TBMQ. To streamline the process, you can either assign the value of the token field to an environment variable named ACCESS_TOKEN or directly replace occurrences of the $ACCESS_TOKEN string within the requests outlined in this tutorial.

export ACCESS_TOKEN=PLACE_YOUR_TOKEN_HERE

Create/update 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"
}'

Upon executing the aforementioned request, an entity will be created within the PostgreSQL database, and a Kafka topic named tbmq.msg.app.shared.test.topic will be added. The Kafka topic will consist of a single partition.

The construction of the topic name is determined by mapping the MQTT topic filter to the corresponding Kafka topic. This mapping is achieved by following a specific naming convention (MQTT topic filter -> Kafka topic).

test/topic -> tbmq.msg.app.shared.test.topic
test/# -> tbmq.msg.app.shared.test.mlw
test/+ -> tbmq.msg.app.shared.test.slw

where

tbmq.msg.app.shared. is added as a prefix
/ is replaced by .
# is replaced by mlw (multi-lvl wildcard)
+ is replaced by slw (single-lvl wildcard)

If the MQTT topic filter contains any special characters not mentioned earlier (other than alphanumeric characters), the hash derived from the topic filter will be utilized to create the Kafka topic. This approach ensures that the resulting Kafka topic remains valid and adheres to the necessary naming conventions.

tbmq.msg.app.shared.$TOPIC_FILTER_HASH

The behavior described above can be regulated by the TB_APP_PERSISTED_MSG_SHARED_TOPIC_VALIDATION property. By default, this variable is enabled, meaning that the validation process is active, ensuring proper topic creation. However, if you choose to disable this validation by setting the variable to false, the system will no longer create Kafka topics for shared subscriptions having topic filters with special characters, resulting in a failure to create the corresponding topics. It’s important to consider this when configuring your environment and handling client IDs with special characters.

Please be aware that once the entity is created, it is not possible to update the partitions or topicFilter fields. Therefore, it is crucial to carefully consider the desired topic filter and the number of partitions before creating the entity. It is recommended to create the entity with a greater number of partitions rather than fewer. This allows for horizontal scalability by accommodating the addition of new clients to the shared subscription in the future. In situations where the entity has been created with improper values or configurations, it becomes necessary to delete the entity and subsequently create a new one with the correct values. Thus, it is essential to exercise caution and make well-informed decisions during the initial creation process to avoid the need for subsequent modifications or recreations.

As an example, if you anticipate having a topic filter to which 5 clients will be subscribed, it is advisable to configure the number of partitions as a multiple of 5, such as 5, 10, or 15. By doing so, you ensure that the load is evenly distributed among the subscribers, promoting balanced processing and improved performance.

Get all Application Shared Subscription entities

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

Note, pageSize parameter equal to 100 and page parameter equal to 0, so the above request will fetch first 100 application shared subscription entities.

Delete Application Shared Subscription entity

Once you delete Application Shared Subscription entity, the respectful Kafka topic will also be deleted. Note, for this TB_KAFKA_ENABLE_TOPIC_DELETION environment variable should be set to true.

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

Paste actual ID of the Application shared subscription entity you want to delete instead of $APP_SHARED_SUBS_ID.