API docs by Redocly

Digital Twin Registry Bulk API (v1)

Download OpenAPI specification:Download

The Single Point of Information about the existence of Digital Twins and their Aspects.
The Digital Twin Registry Bulk API provides methods to create, update (replace), partially update or delete large amounts of data in a single request.
All requests are executed synchronously. For this reason, there are different limits on the amount of data for the individual endpoints.
The payload of one request must not be larger than 128 KB. The operations are atomic.
I.e., operations are executed such that either all requested manipulations fully succeed or nothing at all is changed. As soon as one error occurs in one of the data manipulations, the entire operation is rolled back.

The Digital Twin Registry Bulk API provides offset pagination and cursor pagination, both methodologies partition the entities of a larger dataset, based on various criteria.

Offset pagination is the "traditional" way of paginating through a dataset. It gives the user slightly finer control over the iteration, insofar as e.g. it presents the option to select the desired page index.
Cursor pagination is broadly intended for continuous pagination and therefore lacks the option of selecting a specific page index, in favor of basing the pagination on a specific cursor, provided by the back-end in the first response (assuming the dataset has more than one page).
In cursor pagination, once the client obtains the first page and a cursor for the next one, it can send the next request with that cursor as an argument, in order to fetch the next page.
Cursor pagination avails of logarithmic solutions to scroll through a sorted dataset, which tends to perform increasingly better than offset pagination, the larger the dataset and the closer to its end data is being fetched.
In other words, cursor pagination is preferable to offset pagination in the vast majority of use cases.

The endpoints feature both offset and cursor pagination based on the request parametrization: if RQL limit(x,y) is used, offset pagination will be used - conversely, if the limit and cursor arguments are used in the request body, cursor pagination will be used.
The criterion common to both methodologies is the size of the page, expressed as:

  • the second argument to the RQL limit function (e.g. limit(x, *y*)) for offset-based pagination
  • the limit argument expressed in the request body for using cursor pagination (e.g. "limit": 50)

Authentication

The API offers currently one form of authentication:

  • OAuth2 - An open protocol to allow secure authorization in a simple and standard method from web, mobile and desktop applications.

Digital Twin Bulk

Creates Twins

Creates all Twins.

Authorizations:
macma
path Parameters
tenantId
required
string <uuid>

Unique identifier of the owning tenant.

Request Body schema: application/json
required

Bulk object that contains a list of Twins to create.

required
Array of objects (DigitalTwinCreateDto) unique

Responses

Request samples

Content type
application/json
{
  • "items": [
    ]
}

Response samples

Content type
application/json
{
  • "created": 50
}

Deletes Twins

Deletes all Twins. Twins to be deleted are specified by a list of Twin IDs.
If one or more of the Twin Ids do not exist, the operation succeeds nevertheless without error
(the resulting state after delete would be the same as if these Twins existed).

Maximum 5000 can be deleted.

Authorizations:
macma
path Parameters
tenantId
required
string <uuid>

Unique identifier of the owning tenant.

Request Body schema: application/json
required

Bulk object to define an operation that will delete all Twins with the given Ids.

items
required
Array of integers <int64> non-empty unique [ items <int64 > ]

Responses

Request samples

Content type
application/json
{
  • "items": [
    ]
}

Response samples

Content type
application/json
{
  • "totalAffectedItems": 50,
  • "itemCount": 50
}

Merge Twins

Performs a partial update on all Twins. The Twins are identified by a list of Twin Ids.
Only properties present in the payload will be updated, all other properties will be left intact.
The set of Labels, if present, denotes the desired target state. Any Labels already present on the Twin and not listed here will be deleted.
The API uses the JSON Merge Patch convention see https://datatracker.ietf.org/doc/html/rfc7386.

Maximum 20.000 Twins can be deleted.

Authorizations:
macma
path Parameters
tenantId
required
string <uuid>

Unique identifier of the owning tenant.

Request Body schema: application/json
required

Bulk object to define an operation that will patch all Twins with the given Ids.

twinType
string or null <= 128 characters

The type of the Twin

twinCategory
string or null <= 128 characters

The category of the Twin

description
string or null <= 4000 characters

Detailed description of the Twin

manufacturer
string or null <= 128 characters

Manufacturer of the physical asset represented by the Twin

labels
Array of strings or null <= 10 items unique

Labels of the Twin. Denotes the target state. Any labels already present on the Twin and not listed here will be deleted.

groups
Array of integers or null <int64> (EntityId) <= 50 items unique

Groups the Twin belongs to. Denotes the target state. Any groups already assigned to the Twin and not listed here will be unasigned.

listOperator
string (ListOperator)
Default: "replace"
Enum: "replace" "add" "remove"

Operator to specify the kind of operation to perform on lists given within the body. Add/Remove operations featuring null or empty values produce no effect. Add/Remove operator adds / removes a single element. Replace replaces the entire list.

items
required
Array of integers <int64> non-empty unique [ items <int64 > ]

Responses

Request samples

Content type
application/json
{
  • "twinType": "Bosch Nexo cordless Wi-Fi nutrunner",
  • "twinCategory": "Drill",
  • "description": "On Nexo the complete control unit is in the nutrunner – the first of its kind.",
  • "manufacturer": "Bosch",
  • "labels": [
    ],
  • "groups": [
    ],
  • "listOperator": "replace",
  • "items": [
    ]
}

Response samples

Content type
application/json
{
  • "totalAffectedItems": 50,
  • "itemCount": 50
}

Deletes Twins by Twin RQL Query

Deletes all Twins. Twins to be deleted are specified by an RQL query on Twin properties.
Maximum 5000 Twins can be deleted.

Example RQL queries:

  1. If twins are less than quota, no nextCursor is returned, representing that there are no further calls needed.
    {
  "query": "filter=in(labels.name,\"Label\")"
}
  2. If twins are more than quota, nextCursor is set, representing that there are additional calls needed.
    {
  "query": "filter=in(labels.name,\"Shared Label\")"
}
  3. If limit is more than quota, an error is returned. Otherwise if there are more twins, nextCursor is set, representing that there are additional calls needed.
    {
  "query": "filter=in(labels.name,\"Label\")",
  "limit": 10000
}
  4. Offset pagination is used and from page number the page size twins are deleted.
    {
  "query": "filter=in(labels.name,\"Label\")&option=limit(0,500)",
}
  5. Offset pagination cannot be mixed with cursor pagination and 400 HTTP code is returned.
    {
  "query": "filter=in(labels.name,\"Label\")&option=limit(0,500)",
  "cursor": <NEXT_CURSOR>,
  "limit": 500
}
    Note: is the value from the response body of the previous request.
    More information about RQL usage in Digital Twin Registry can be found in the Documentation.
Authorizations:
macma
path Parameters
tenantId
required
string <uuid>

Unique identifier of the owning tenant.

Request Body schema: application/json
required

Bulk object to define an operation that will delete all Twins that match the given Twin RQL query.

query
required
string

RQL query string. For more examples, see operation description above.

cursor
string or null

set cursor to nextCursor returned by the previous call to list items in the next page.

limit
integer or null <int32> >= 0
Default: 0

the size of the requested page. Defaults to the maximum quota defined for the endpoint.

Responses

Request samples

Content type
application/json
{
  • "query": "filter=in(labels.name,\"Label\")",
  • "cursor": "MjAzNA==",
  • "limit": 0
}

Response samples

Content type
application/json
{
  • "totalAffectedItems": 50,
  • "queryMatchCount": 50,
  • "nextCursor": "MjAzNA=="
}

Merge Twins by Twin RQL Query

Performs a partial update on all Twins.
The Twins are identified by an RQL query where all matching Twins will be updated. Only properties present in the payload will be updated, all other properties will be left intact.
The set of Labels, if present, denotes the desired target state. Any Labels already present on the Twin and not listed here will be deleted.
The API uses the JSON Merge Patch convention - RFC 7386.

Maximum 20.000 Twins can be updated.

Example RQL queries:

  1. If twins are less than quota, no nextCursor is returned, representing that there are no further calls needed.
    {
  "query": "filter=in(labels.name,\"Label\")"
}
  2. If twins are more than quota, nextCursor is set, representing that there are additional calls needed.
    {
  "query": "filter=in(labels.name,\"Shared Label\")"
}
  3. If limit is more than quota, an error is returned. Otherwise if there are more twins, nextCursor is set, representing that there are additional calls needed.
    {
  "query": "filter=in(labels.name,\"Label\")",
  "limit": 30000
}
  4. Offset pagination is used and from page number the page size twins are partially updated.
    {
  "query": "filter=in(labels.name,\"Label\")&option=limit(0,500)",
}
  5. Offset pagination cannot be mixed with cursor pagination and 400 HTTP code is returned.
    {
  "query": "filter=in(labels.name,\"Label\")&option=limit(0,500)",
  "cursor": <NEXT_CURSOR>,
  "limit": 500
}
    Note: is the value from the response body of the previous request.
    More information about RQL usage in Digital Twin Registry can be found in the Documentation.
Authorizations:
macma
path Parameters
tenantId
required
string <uuid>

Unique identifier of the owning tenant.

Request Body schema: application/json
required

Bulk object to define an operation that will patch all Twins that match the given Twin RQL query.

twinType
string or null <= 128 characters

The type of the Twin

twinCategory
string or null <= 128 characters

The category of the Twin

description
string or null <= 4000 characters

Detailed description of the Twin

manufacturer
string or null <= 128 characters

Manufacturer of the physical asset represented by the Twin

labels
Array of strings or null <= 10 items unique

Labels of the Twin. Denotes the target state. Any labels already present on the Twin and not listed here will be deleted.

groups
Array of integers or null <int64> (EntityId) <= 50 items unique

Groups the Twin belongs to. Denotes the target state. Any groups already assigned to the Twin and not listed here will be unasigned.

listOperator
string (ListOperator)
Default: "replace"
Enum: "replace" "add" "remove"

Operator to specify the kind of operation to perform on lists given within the body. Add/Remove operations featuring null or empty values produce no effect. Add/Remove operator adds / removes a single element. Replace replaces the entire list.

query
required
string

RQL query string. For more examples, see operation description above.

cursor
string or null

set cursor to nextCursor returned by the previous call to list items in the next page.

limit
integer or null <int32> >= 0
Default: 0

the size of the requested page. Defaults to the maximum quota defined for the endpoint.

Responses

Request samples

Content type
application/json
{
  • "twinType": "Bosch Nexo cordless Wi-Fi nutrunner",
  • "twinCategory": "Drill",
  • "description": "On Nexo the complete control unit is in the nutrunner – the first of its kind.",
  • "manufacturer": "Bosch",
  • "labels": [
    ],
  • "groups": [
    ],
  • "listOperator": "replace",
  • "query": "filter=in(labels.name,\"Label\")",
  • "cursor": "MjAzNA==",
  • "limit": 0
}

Response samples

Content type
application/json
{
  • "totalAffectedItems": 50,
  • "queryMatchCount": 50,
  • "nextCursor": "MjAzNA=="
}

Creates Twins if not exist

Creates the given Twins, provided they to not yet exist in the registry. Assumes a Twin exists if at least one of the local identifiers match a local identifier of a Twin in the registry. Existing Twins will not be touched.

Authorizations:
macma
path Parameters
tenantId
required
string <uuid>

Unique identifier of the owning tenant.

Request Body schema: application/json
required

Bulk object that contains a list of Twins to create.

required
Array of objects (DigitalTwinCreateDto) unique

Responses

Request samples

Content type
application/json
{
  • "items": [
    ]
}

Response samples

Content type
application/json
{
  • "created": 50
}

Creates or replace Twins

Creates the given Twins, provided they do not exist in the registry. Assumes a Twin exists if at least one of the local identifiers match a local identifier of a Twin in the registry.
Existing Twins should be updated, but this is currently not supported.

Authorizations:
macma
path Parameters
tenantId
required
string <uuid>

Unique identifier of the owning tenant.

Request Body schema: application/json
required

Bulk object that contains a list of Twins to create.

required
Array of objects (DigitalTwinCreateDto) unique

Responses

Request samples

Content type
application/json
{
  • "items": [
    ]
}

Response samples

Content type
application/json
{
  • "totalAffectedItems": 50,
  • "created": 50,
  • "updated": 50
}

Aspect Bulk

Creates Aspects by Twin RQL query

Creates all Aspects for each Twin that match the RQL query on Twin properties.
Limit for creation is 4000 Aspects.

Example RQL queries:

  1. If twins * aspects to create are less than quota, no nextCursor is returned, representing that there are no further calls needed.
    {
  "query": "filter=in(labels.name,\"Label\")"
}
  2. If twins * aspects to create are more than quota, nextCursor is set, representing that there are additional calls needed.
    {
  "query": "filter=in(labels.name,\"Shared Label\")"
}
  3. If limit twins * aspects is more than quota, an error is returned. Otherwise if there are more twins to create aspects for, nextCursor is set, representing that there are additional calls needed.
    {
  "query": "filter=in(labels.name,\"Label\")",
  "limit": 5000
}
  4. Offset pagination is used and aspects are created for the page number, the page size twins.
    {
  "query": "filter=in(labels.name,\"Label\")&option=limit(0,500)",
}
  5. Offset pagination cannot be mixed with cursor pagination and 400 HTTP code is returned.
    {
  "query": "filter=in(labels.name,\"Label\")&option=limit(0,500)",
  "cursor": <NEXT_CURSOR>,
  "limit": 500
}
    Note: is the value from the response body of the previous request.
    More information about RQL usage in Digital Twin Registry can be found in the Documentation.
Authorizations:
macma
path Parameters
tenantId
required
string <uuid>

Unique identifier of the owning tenant.

Request Body schema: application/json
required

Bulk object to define an operation that will create all given Aspects for all Twins that match the given Twin RQL query.

required
Array of objects (AspectCreateDto) unique
query
required
string

RQL query string. For more examples, see operation description above.

cursor
string or null

set cursor to nextCursor returned by the previous call to list items in the next page.

limit
integer or null <int32> >= 0
Default: 0

the size of the requested page. Defaults to the maximum quota defined for the endpoint.

Responses

Request samples

Content type
application/json
{
  • "items": [
    ],
  • "query": "filter=in(labels.name,\"Label\")",
  • "cursor": "MjAzNA==",
  • "limit": 0
}

Response samples

Content type
application/json
{
  • "totalAffectedItems": 50,
  • "queryMatchCount": 50,
  • "nextCursor": "MjAzNA=="
}

Deletes all Aspects by Twin RQL query

Deletes all Aspects for each Twin that match the RQL query on Twin properties.
Limit of matched Twins are 4000.

Example RQL queries:

  1. If twins are less than quota, no nextCursor is returned, representing that there are no further calls needed.
    {
  "query": "filter=in(digitalTwin.labels.name,\"Label\")"
}
  2. If twins are more than quota, nextCursor is set, representing that there are additional calls needed.
    {
  "query": "filter=in(digitalTwin.labels.name,\"Shared Label\")"
}
  3. If limit is more than quota, an error is returned. Otherwise if there are more twins, nextCursor is set, representing that there are additional calls needed.
    {
  "query": "filter=in(digitalTwin.labels.name,\"Label\")",
  "limit": 10000
}
  4. Offset pagination is used and from page number the page size twins are deleted.
    {
  "query": "filter=in(digitalTwin.labels.name,\"Label\")&option=limit(0,500)",
}
  5. Offset pagination cannot be mixed with cursor pagination and 400 HTTP code is returned.
    {
  "query": "filter=in(digitalTwin.labels.name,\"Label\")&option=limit(0,500)",
  "cursor": <NEXT_CURSOR>,
  "limit": 500
}
    Note: is the value from the response body of the previous request.
    More information about RQL usage in Digital Twin Registry can be found in the Documentation.
Authorizations:
macma
path Parameters
tenantId
required
string <uuid>

Unique identifier of the owning tenant.

Request Body schema: application/json
required

Bulk object to define an operation that will delete all Aspects that match the given Aspect RQL query.

query
required
string

RQL query string. For more examples, see operation description above.

cursor
string or null

set cursor to nextCursor returned by the previous call to list items in the next page.

limit
integer or null <int32> >= 0
Default: 0

the size of the requested page. Defaults to the maximum quota defined for the endpoint.

Responses

Request samples

Content type
application/json
{
  • "query": "filter=in(labels.name,\"Label\")",
  • "cursor": "MjAzNA==",
  • "limit": 0
}

Response samples

Content type
application/json
{
  • "totalAffectedItems": 50,
  • "queryMatchCount": 50,
  • "nextCursor": "MjAzNA=="
}

Merge all Aspects by Aspect RQL query

Performs a partial update on all Aspects.
The Aspects are identified by an RQL query on Aspect properties. Currently just the model reference will be updated, all other properties will be left intact. The API uses the JSON Merge Patch convention - RFC 7386.

Maximum 4000 aspects can be updated.

Example RQL queries:

  1. If aspects are less than quota, no nextCursor is returned, representing that there are no further calls needed.
    {
  "query": "filter=in(digitalTwin.labels.name,\"Label\")"
}
  2. If aspects more are than quota, nextCursor is set, representing that there are additional calls needed.
    {
  "query": "filter=in(digitalTwin.labels.name,\"Shared Label\")"
}
  3. If limit is more than quota, an error is returned. Otherwise if there are more aspects, nextCursor is set, representing that there are additional calls needed.
    {
  "query": "eq(modelReference.urn,\"urn:samm:com.bosch.nexeed.digitaltwin:1.0.0#Errors\")",
  "limit": 10000
}
  4. Offset pagination is used and from page number the page size aspects are partially updated.
    {
  "query": "filter=in(digitalTwin.labels.name,\"Label\")&option=limit(0,500)",
}
  5. Offset pagination cannot be mixed with cursor pagination and 400 HTTP code is returned.
    {
  "query": "filter=in(digitalTwin.labels.name,\"Label\")&option=limit(0,500)",
  "cursor": <NEXT_CURSOR>,
  "limit": 500
}
    Note: is the value from the response body of the previous request.
    More information about RQL usage in Digital Twin Registry can be found in the Documentation.
Authorizations:
macma
path Parameters
tenantId
required
string <uuid>

Unique identifier of the owning tenant.

Request Body schema: application/json
required

Bulk object to define an update to the given model URN for all Aspects that match the given Aspect RQL query.

required
object (ModelReferenceCreateReplaceDto)

Model reference of the Aspect

query
required
string

RQL query string. For more examples, see operation description above.

cursor
string or null

set cursor to nextCursor returned by the previous call to list items in the next page.

limit
integer or null <int32> >= 0
Default: 0

the size of the requested page. Defaults to the maximum quota defined for the endpoint.

Responses

Request samples

Content type
application/json
{
  • "modelReference": {
    },
  • "query": "filter=in(labels.name,\"Label\")",
  • "cursor": "MjAzNA==",
  • "limit": 0
}

Response samples

Content type
application/json
{
  • "totalAffectedItems": 50,
  • "queryMatchCount": 50,
  • "nextCursor": "MjAzNA=="
}

Deletes all Aspects by Aspect RQL query

Deletes all Aspects that match the RQL query on Aspect properties.

Maximum 4000 Aspects can be deleted.

Example RQL queries:

  1. If matched Aspects are less than quota, no nextCursor is returned, representing that there are no further calls needed.
    {
  "query": "filter=in(digitalTwin.labels.name,\"Label\")"
}
  2. If matched Aspects more are than quota, nextCursor is set, representing that there are additional calls needed.
    {
  "query": "filter=in(digitalTwin.labels.name,\"Shared Label\")"
}
  3. If limit is more than quota, an error is returned. Otherwise if there are more aspects, nextCursor is set, representing that there are additional calls needed.
    {
  "query": "eq(modelReference.urn,\"urn:samm:com.bosch.nexeed.digitaltwin:1.0.0#Errors\")",
  "limit": 10000
}
  4. Offset pagination is used and from page number the page size Aspects are deleted.
    {
  "query": "filter=in(digitalTwin.labels.name,\"Label\")&option=limit(0,500)",
}
  5. Offset pagination cannot be mixed with cursor pagination and 400 HTTP code is returned.
    {
  "query": "filter=in(digitalTwin.labels.name,\"Label\")&option=limit(0,500)",
  "cursor": <NEXT_CURSOR>,
  "limit": 500
}
    Note: is the value from the response body of the previous request.
    More information about RQL usage in Digital Twin Registry can be found in the Documentation.
Authorizations:
macma
path Parameters
tenantId
required
string <uuid>

Unique identifier of the owning tenant.

Request Body schema: application/json
required

Bulk object to define an operation that will delete all Aspects that match the given Aspect RQL query.

query
required
string

RQL query string. For more examples, see operation description above.

cursor
string or null

set cursor to nextCursor returned by the previous call to list items in the next page.

limit
integer or null <int32> >= 0
Default: 0

the size of the requested page. Defaults to the maximum quota defined for the endpoint.

Responses

Request samples

Content type
application/json
{
  • "query": "filter=in(labels.name,\"Label\")",
  • "cursor": "MjAzNA==",
  • "limit": 0
}

Response samples

Content type
application/json
{
  • "totalAffectedItems": 50,
  • "queryMatchCount": 50,
  • "nextCursor": "MjAzNA=="
}

Creates Aspects of a Twin

Creates all Aspects of a Twin.

Authorizations:
macma
path Parameters
tenantId
required
string <uuid>

Unique identifier of the owning tenant.

twinId
required
integer <int64>

Unique identifier of the Twin.

Request Body schema: application/json
required

Bulk object to define an operation that will create all given Aspects of a Twin.

required
Array of objects (AspectCreateDto) unique

Responses

Request samples

Content type
application/json
{
  • "items": [
    ]
}

Response samples

Content type
application/json
{
  • "created": 50
}

Replaces Aspects of a Twin

Replaces all Aspects of a Twin.
The Aspects defined in the payload will replace the existing Aspects of the Twin.

Authorizations:
macma
path Parameters
tenantId
required
string <uuid>

Unique identifier of the owning tenant.

twinId
required
integer <int64>

Unique identifier of the Twin.

Request Body schema: application/json
required

Bulk object to define an update of all given Aspects of a Twin.

required
Array of objects (AspectReplaceBulkDto) unique

Responses

Request samples

Content type
application/json
{
  • "items": [
    ]
}

Response samples

Content type
application/json
{
  • "totalAffectedItems": 50,
  • "itemCount": 50
}

Deletes Aspects of a Twin

Deletes all Aspects of a Twin by a list of Aspects Unique identifiers.
Non-existent Aspects are ignored.

Authorizations:
macma
path Parameters
tenantId
required
string <uuid>

Unique identifier of the owning tenant.

twinId
required
integer <int64>

Unique identifier of the Twin.

Request Body schema: application/json
required

Bulk object to define an operation that will delete all Aspects with the given Ids of a Twin.

items
required
Array of integers <int64> non-empty unique [ items <int64 > ]

Responses

Request samples

Content type
application/json
{
  • "items": [
    ]
}