Digital Twin Registry Async API
Process asynchronous commands with the Digital Twin Registry Async API for event-driven architectures.
This page explains how to access and use the API, connect to the underlying Apache Kafka topics, produce commands, and consume the messages from the API’s response.
| The Digital Twin Registry Async API is currently in a preview state. Therefore, this API is only available on request. For enabling the Digital Twin Registry Async API for your tenant, click the following link to find a prepared email with placeholders for all required content: support.semantic-stack@bosch.com |
Enable the Digital Twin Registry Async API for my tenant
Hello Bosch Semantic Stack team,
I would like to have the Digital Twin Registry Async API enabled within the Bosch Semantic Stack application for the following tenant:
<insert your tenant ID here>
Thanks!
Accessing the Digital Twin Registry Async API
The Digital Twin Registry Async API requires authentication.
Obtain the necessary credentials as follows:
-
At the Access Management portal, assign the Message Operator role to the respective user (a person or a technical client). For a general role overview, see also Concepts > Authorization.
-
At the Digital Twin Registry Async Credentials API (REST):
-
For authentication, generate a bearer token (OAuth2).
-
With the token, request your credentials. For details, refer to the corresponding OpenAPI description
.
-
Using the Digital Twin Registry Async API
The Digital Twin Registry Async API uses the Apache Kafka messaging system.
Topic names
The Digital Twin Registry Async API uses the following topics for communication:
| Topic name | Short name | Description |
|---|---|---|
|
command topic |
The topic for your client to send commands to the Digital Twin Registry. |
|
response topic |
The topic used by the Digital Twin Registry to send the responses back to the client. |
AsyncAPI document
For details on the Digital Twin Registry Async API, refer to its AsyncAPI document:
https://registry.bosch-semantic-stack.com/docs/async/api-doc-async.html
The provided AsyncAPI document complies with the
AsyncAPI Specification.
Integration with the Digital Twin Registry Async API
To generate client code for integration with the Digital Twin Registry Async API, download the AsyncAPI document.
For setting up your client application, the following resources might be helpful:
-
For more information about value object generation support: Modelina Project
-
For extensive documentation on how client applications can be set up to connect to their Apache Kafka topics: the Confluent documentation
API usage essentials
Key points for optimal implementation and performance of the Digital Twin Registry Async API:
-
Best practice: Unique message correlation ID
-
Required: Naming the message schema
-
Usage tips:
-
API design implication: No Kafka transactions
Unique message correlation ID
The correlation-id header is used to correlate the request and response messages in the Digital Twin Registry Async API.
Although the Digital Twin Registry will not enforce the uniqueness of the correlation-id header, it is strongly recommended to use unique values for each command.
The Digital Twin Registry will include it in the response message as-is for the client to be able to correlate the request and response messages.
If the correlation-id header is missing, the Digital Twin Registry ignores the message and does not send a response.
|
Naming the message schema
The schema-name header defines the name of the message schema.
Each message sent to the Digital Twin Registry Async API must contain an appropriate schema-name Apache Kafka header.
This is vital, because this header is later used by the consumer to determine the JSON schema to be used for deserialization.
If the schema-name header is missing, the Digital Twin Registry ignores the message and does not send a response.
|
Deserializing the response messages
The response messages sent by the Digital Twin Registry will contain the schema-name header in the same way as it is used in the commands.
The schema-name header can be used to determine the JSON schema to be used for deserialization.
|
If the client implemented or generated each of the possible models used by the responses, then the selection process between the models is trivial since there is a one-to-one mapping between the schema name and the model.
Using compression
To maximize the throughput of the Digital Twin Registry Async API, use compression when sending messages to the command topic.
Apache Kafka has a built-in support for compression, which can be used via the compression.type property.
For more information on compression, refer to the corresponding Confluent documentation.
Partitioning topics
To maximize the throughput of the Digital Twin Registry Async API, consider implementing a partition strategy.
The Digital Twin Registry Async API can use multiple partitions for both the command and the response topics. This can help with increasing the throughput of the Digital Twin Registry Async API but only if the client application is using all available partitions.
At the same time, it is important to note that the order of the messages sent to the command topic is only guaranteed within a partition. Therefore, the client applications must select the right partitioning strategy that fits their needs both in terms of performance and ordering.
For more information on partitioning strategies, refer to the corresponding Confluent documentation.
Acknowledging messages
To send a large number of messages to the command topic in a short period of time, leverage the acks configuration property.
Determine an acks value that best supports your use case.
For more information on the acks configuration property, refer to the corresponding Confluent documentation.
No Kafka transactions
The Digital Twin Registry Async API does not support Kafka transactions at the moment. This means that both in case of the command and the response topics, the messages are not transactional.
As a consequence of this design decision, the Digital Twin Registry can process incoming commands faster. Note, however, that consumers of the response topic might see identical messages multiple times.