All topics contain the <channel> which may be either twin or live.
For the meaning of those two channels see Protocol specification.
Create a Thing
This command creates the thing specified by the <namespace> and <thingId> in the topic defined by the JSON in the
value.
The Policy of the created
Thing must include at least one subject authorized to have READ, WRITE permissions.
If no Policy is provided within the command, a default Policy with an entry for the authorized subject with
all permissions set to true will be created.
Command
| Field | Value |
|---|---|
| topic | <namespace>/<thingName>/things/<channel>/commands/create |
| path | / |
| value | The complete thing as JSON object, see Ditto protocol payload (JSON). |
Response
| Field | Value | |
|---|---|---|
| topic | <namespace>/<thingName>/things/<channel>/commands/create |
|
| path | / |
|
| value | The created Thing as JSON object, see Ditto protocol payload (JSON). | |
| status | code | |
201 |
Success - the thing was created successfully. |
Event
The event emitted by Ditto after a thing was created.
| Field | Value |
|---|---|
| topic | <namespace>/<thingName>/things/<channel>/events/created |
| path | / |
| value | The created thing as JSON object, see Ditto protocol payload (JSON) |
Example: Create a Thing.
Create or modify a Thing
This command modifies the thing specified by the <namespace> and <thingId> in the topic with the JSON in the
value, if it already exists. Otherwise, the thing is created.
Command
| Field | Value |
|---|---|
| topic | <namespace>/<thingName>/things/<channel>/commands/modify |
| path | / |
| value | The complete thing as JSON. see Ditto protocol payload (JSON) |
For modifying an existing thing, the authorized subject needs WRITE permission.
If the thing does not yet exist, the same rules apply as described for the create command.
Response
If the Thing was created successfully:
| Field | Value | |
|---|---|---|
| topic | <namespace>/<thingName>/things/<channel>/commands/create |
|
| path | / |
|
| value | The created Thing as JSON object, see Ditto protocol payload (JSON). | |
| status | code | |
201 |
Success - the Thing was created successfully. |
If the Thing was modified successfully:
| Field | Value | |
|---|---|---|
| topic | <namespace>/<thingName>/things/<channel>/commands/modify |
|
| path | / |
|
| value | This field is not available, if the Thing already existed. | |
| status | code | |
204 |
Success - the Thing was modified successfully. |
Event
The event emitted by Ditto after a thing was modified.
| Field | Value |
|---|---|
| topic | <namespace>/<thingName>/things/<channel>/events/modified |
| path | / |
| value | The modified Thing as JSON see Ditto protocol payload (JSON). |
Example: Modify a Thing
In case a thing was created, the event described for the create command will be emitted.
Create or modify all Attributes of a Thing
Create or modify the Attributes of a Thing identified by the <namespace> and <thingId> in the topic.
The Attributes will be replaced by the JSON in the value.
Command
| Field | Value |
|---|---|
| topic | <namespace>/<thingName>/things/<channel>/commands/modify |
| path | /attributes |
| value | The attributes of the thing as JSON, see property attributes of Things JSON schema. See Ditto protocol payload (JSON). |
Response
| Field | Value | |
|---|---|---|
| topic | <namespace>/<thingName>/things/<channel>/commands/modify |
|
| path | /attributes |
|
| value | The created attributes as JSON, see property attributes of Things JSON schema. See Ditto protocol payload (JSON).. This field is not available, if the thing already contained attributes. |
|
| status | code | |
201 |
Success - Attributes were created successfully. | |
204 |
Success - Attributes were modified successfully. |
Event
If the thing already contained attributes before the command was applied and they were thus overwritten, a modified
event will be emitted.
| Field | Value |
|---|---|
| topic | <namespace>/<thingName>/things/<channel>/events/modified |
| path | /attributes |
| value | The modified attributes of the thing as JSON, see property attributes of the Things JSON schema. See Ditto protocol payload (JSON). |
Example: Modify Attributes
If the thing did not yet contain attributes before the command was applied, a created event will be emitted.
| Field | Value |
|---|---|
| topic | <namespace>/<thingName>/things/<channel>/events/created |
| path | /attributes |
| value | The created Attributes of the Thing as JSON, see property attributes of the Things JSON schema at Ditto protocol payload (JSON). |
Example: Create Attributes
Create or modify a single Attribute of a Thing
Create or modify a specific attribute identified by the <attributePath> of the Thing.
The attribute will be created in case it doesn’t exist yet, otherwise the thing attribute is updated.
The attribute (JSON) can be referenced hierarchically by applying JSON Pointer notation (RFC-6901).
Command
| Field | Value |
|---|---|
| topic | <namespace>/<thingName>/things/<channel>/commands/modify |
| path | /attributes/<attributePath> |
| value | The specific attribute of the Thing as JSON. |
Response
| Field | Value | |
|---|---|---|
| topic | <namespace>/<thingName>/things/<channel>/commands/modify |
|
| path | /attributes/<attributePath> |
|
| value | The created attribute as JSON. This field is not available, if the attribute already existed. | |
| status | code | |
201 |
Success - The Attribute was created successfully. | |
204 |
Success - The Attribute was modified successfully. |
Event
If the attribute already existed before the command was applied and it was thus overwritten by the command, a
modified event will be emitted.
| Field | Value |
|---|---|
| topic | <namespace>/<thingName>/things/<channel>/events/modified |
| path | /attributes/<attributePath> |
| value | The modified Attribute of the Thing as JSON value. |
Example: Modify a single Attribute
If the attribute did not yet exist before the command was applied, a created event will be emitted.
| Field | Value |
|---|---|
| topic | <namespace>/<thingName>/things/<channel>/events/created |
| path | /attributes/<attributePath> |
| value | The created Attribute of the Thing as JSON value. |
Example: Create a single Attribute
Create or modify a single definition of a Thing
Create or modify a definition of the Thing. The definition will be created in case it doesn’t exist yet, otherwise the thing definition is updated.
Command
| Field | Value |
|---|---|
| topic | <namespace>/<thingName>/things/<channel>/commands/modify |
| path | /definition |
| value | The specific definition of the Thing as JSON string value. |
Response
| Field | Value | |
|---|---|---|
| topic | <namespace>/<thingName>/things/<channel>/commands/modify |
|
| path | /definition |
|
| value | The created definition as JSON string value. This field is not available, if the definition already existed. | |
| status | code | |
201 |
Success - The definition was created successfully. | |
204 |
Success - The definition was modified successfully. |
Event
If the definition already existed before the command was applied and it was thus overwritten by the command, a
modified event will be emitted.
| Field | Value |
|---|---|
| topic | <namespace>/<thingName>/things/<channel>/events/modified |
| path | /definition |
| value | The modified definition of the Thing as JSON string value. |
Example: Modify a definition
If the definition did not yet exist before the command was applied, a created event will be emitted.
| Field | Value |
|---|---|
| topic | <namespace>/<thingName>/things/<channel>/events/created |
| path | /definition |
| value | The created definition of the Thing as JSON string value. |
Example: Create a definition
Create or modify all Features of a Thing
Create or modify the Features of a Thing identified by the <namespace> and the <thingId> in the topic.
The list of Features will be replaced by the JSON in the value.
Command
| Field | Value |
|---|---|
| topic | <namespace>/<thingName>/things/<channel>/commands/modify |
| path | /features |
| value | All Features of the Thing as JSON, see property features of Things JSON schema. See Ditto protocol payload (JSON). |
Response
| Field | Value | |
|---|---|---|
| topic | <namespace>/<thingName>/things/<channel>/commands/modify |
|
| path | /features |
|
| value | The created Features as JSON, see property features of Things JSON schema at Ditto protocol payload (JSON). This field is not available, if the thing already contained features. |
|
| status | code | |
201 |
Success - The Features were created successfully. | |
204 |
Success - The Features were modified successfully. |
Event
If the thing already contained Features before the command was applied and they were thus overwritten, a
modified event will be emitted.
| Field | Value |
|---|---|
| topic | <namespace>/<thingName>/things/<channel>/events/modified |
| path | /features |
| value | All Features of the Thing as JSON, see property features of the Things JSON schema. See Ditto protocol payload (JSON). |
Example: Modify Features
If the thing did not yet contain Features before the command was applied, a created event will be emitted.
| Field | Value |
|---|---|
| topic | <namespace>/<thingName>/things/<channel>/events/created |
| path | /features |
| value | All Features of the Thing as JSON, see property features of the Things JSON schema at Ditto protocol payload (JSON). |
Example: Create Features
Create or modify single Feature of a Thing
Create or modify a specific Feature (identified by the Feature ID in the path) of the Thing (identified by the <namespace> and the <thingId> in the topic).
Command
| Field | Value |
|---|---|
| topic | <namespace>/<thingName>/things/<channel>/commands/modify |
| path | /features/<featureId> |
| value | The specific Feature of the Thing as JSON. See Ditto protocol payload (JSON). |
Response
| Field | Value | |
|---|---|---|
| topic | <namespace>/<thingName>/things/<channel>/commands/modify |
|
| path | /features/<featureId> |
|
| value | The created Feature as JSON. See Ditto protocol payload (JSON). This field is not available, if the Feature already existed. | |
| status | code | |
201 |
Success - The Feature was created successfully. | |
204 |
Success - the Feature was modified successfully. |
Event
If the Feature already existed before the command was applied and it was thus overwritten by the command, a
modified event will be emitted.
| Field | Value |
|---|---|
| topic | <namespace>/<thingName>/things/<channel>/events/modified |
| path | /features/<featureId> |
| value | The modified Feature of the Thing as JSON. See Ditto protocol payload (JSON). |
Example: Modify a single Feature
If the Feature did not yet exist before the command was applied, a created event will be emitted.
| Field | Value |
|---|---|
| topic | <namespace>/<thingName>/things/<channel>/events/created |
| path | /features/<featureId> |
| value | The created Feature of the Thing as JSON. see Ditto protocol payload (JSON). |
Example: Create a single Feature
Create or modify Definition of a Feature
Create or modify the Definition of a Feature (identified by the Feature ID in the path) of the Thing (identified by the <namespace> and the <thingId> in the topic).
Command
| Field | Value |
|---|---|
| topic | <namespace>/<thingName>/things/<channel>/commands/modify |
| path | /features/<featureId>/definition |
| value | The Definition of the Feature as JSON array, see property definition of Things JSON schema. See Ditto protocol payload (JSON). |
Response
| Field | Value | |
|---|---|---|
| topic | <namespace>/<thingName>/things/<channel>/commands/modify |
|
| path | /features/<featureId>/definition |
|
| value | The created Definition of the Feature as JSON array, see property definition of Things JSON schema at Ditto protocol payload (JSON). This field is not available, if the Definition already existed. |
|
| status | code | |
201 |
Success - the Definition was created successfully. | |
204 |
Success - the Definition was modified successfully. |
Event
If the Feature Definition already existed before the command was applied and it was thus overwritten by the command, a
modified event will be emitted.
| Field | Value |
|---|---|
| topic | <namespace>/<thingName>/things/<channel>/events/modified |
| path | /features/<featureId>/definition |
| value | The modified Definition of the Feature as JSON array, see property properties of the Things JSON schema. See Ditto protocol payload (JSON). |
Example: Modify Feature Definition
If the Feature Definition did not yet exist before the command was applied, a created event will be emitted.
| Field | Value |
|---|---|
| topic | <namespace>/<thingName>/things/<channel>/events/created |
| path | /features/<featureId>/definition |
| value | The created Definition of the Feature as JSON array, see property definition of the Things JSON schema at Ditto protocol payload (JSON). |
Example: Create Feature Definition
Modify all Properties of a Feature
Create or modify the Properties of a Feature (identified by the Feature ID in the path) of the Thing (identified by the <namespace> and the <thingId> in the topic).
Command
| Field | Value |
|---|---|
| topic | <namespace>/<thingName>/things/<channel>/commands/modify |
| path | /features/<featureId>/properties |
| value | The Properties of the Feature as JSON, see property properties of Things JSON schema. See Ditto protocol payload (JSON). |
Response
| Field | Value | |
|---|---|---|
| topic | <namespace>/<thingName>/things/<channel>/commands/modify |
|
| path | /features/<featureId>/properties |
|
| value | The created Properties of the Feature as JSON object, see property properties of Things JSON schema at Ditto protocol payload (JSON). This field is not available, if Feature already contained Properties. |
|
| status | code | |
201 |
Success - the Properties were created successfully. | |
204 |
Success - the Properties were modified successfully. |
Event
If the Feature already contained Properties before the command was applied and they were thus overwritten by the
command, a modified event will be emitted.
| Field | Value |
|---|---|
| topic | <namespace>/<thingName>/things/<channel>/events/modified |
| path | /features/<featureId>/properties |
| value | The modified Properties of the Feature as JSON, see property properties of the Things JSON schema. See Ditto protocol payload (JSON). |
Example: Modify Feature Properties
If the Feature did not yet contain Properties before the command was applied, a created event will be emitted.
| Field | Value |
|---|---|
| topic | <namespace>/<thingName>/things/<channel>/events/created |
| path | /features/<featureId>/properties |
| value | The created Properties of the Feature as JSON object, see property properties of the Things JSON schema at Ditto protocol payload (JSON). |
Example: Create Feature Properties
Modify all desired Properties of a Feature
Create or modify the desired Properties of a Feature (identified by the Feature ID in the path) of the Thing (identified by the <namespace> and the <thingId> in the topic).
Command
| Field | Value |
|---|---|
| topic | <namespace>/<thingName>/things/<channel>/commands/modify |
| path | /features/<featureId>/desiredProperties |
| value | The desired Properties of the Feature as JSON, see property desiredProperties of Things JSON schema. See Ditto protocol payload (JSON). |
Response
| Field | Value | |
|---|---|---|
| topic | <namespace>/<thingName>/things/<channel>/commands/modify |
|
| path | /features/<featureId>/desiredProperties |
|
| value | The created desired Properties of the Feature as JSON object, see property desiredProperties of Things JSON schema at Ditto protocol payload (JSON). This field is not available, if Feature already contained desired Properties. |
|
| status | code | |
201 |
Success - the desired Properties were created successfully. | |
204 |
Success - the desired Properties were modified successfully. |
Event
If the Feature already contained desired Properties before the command was applied and they were thus overwritten by the command, a modified event will be emitted.
| Field | Value |
|---|---|
| topic | <namespace>/<thingName>/things/<channel>/events/modified |
| path | /features/<featureId>/desiredProperties |
| value | The modified desired Properties of the Feature as JSON, see property desiredProperties of the Things JSON schema. See Ditto protocol payload (JSON). |
Example: Modify Feature Desired Properties
If the Feature did not yet contain desired Properties before the command was applied, a created event will be emitted.
| Field | Value |
|---|---|
| topic | <namespace>/<thingName>/things/<channel>/events/created |
| path | /features/<featureId>/desiredProperties |
| value | The created desired Properties of the Feature as JSON object, see property desiredProperties of the Things JSON schema at Ditto protocol payload (JSON). |
Example: Create Feature Desired Properties
Create or modify a single Property of a Feature
Create or modify a specific Property (identified by <propertyPath>) of a Feature (identified by the <featureId> in the path).
The Property will be created if it doesn’t exist or else updated.
The Property (JSON) can be referenced hierarchically by applying JSON Pointer notation (RFC-6901).
Command
| Field | Value |
|---|---|
| topic | <namespace>/<thingName>/things/<channel>/commands/modify |
| path | /features/<featureId>/properties/<propertyPath> |
| value | The specific Property of the Feature as JSON. |
Response
| Field | Value | ||
|---|---|---|---|
| topic | <namespace>/<thingName>/things/<channel>/commands/modify |
||
| path | /features/<featureId>/properties/<propertyPath> |
||
| value | The created Property of the Feature as JSON. This field is not available, if the Property already existed. | ||
| status | code | ||
201 |
Success - the Property was created successfully. | ||
204 |
Success - the Property was modified successfully. |
Event
If the Feature Property already existed before the command was applied and it was thus overwritten by the command, a
modified event will be emitted.
| Field | Value |
|---|---|
| topic | <namespace>/<thingName>/things/<channel>/events/modified |
| path | /features/<featureId>/properties/<propertyPath> |
| value | The modified Property of the Thing as JSON. |
Example: Modify a single Feature Property
If the Feature Property did not yet exist before the command was applied, a created event will be emitted.
| Field | Value |
|---|---|
| topic | <namespace>/<thingName>/things/<channel>/events/created |
| path | /features/<featureId>/properties/<propertyPath> |
| value | The created Property of the Thing as JSON. |
Example: Create a single Feature Property
Create or modify a single desired Property of a Feature
Create or modify a specific desired Property (identified by <desiredPropertyPath>) of a Feature (identified by the <featureId> in the path).
The desired Property will be created if it doesn’t exist or else updated.
The Property (JSON) can be referenced hierarchically by applying JSON Pointer notation (RFC-6901).
Command
| Field | Value |
|---|---|
| topic | <namespace>/<thingName>/things/<channel>/commands/modify |
| path | /features/<featureId>/desiredProperties/<desiredPropertyPath> |
| value | The specific desired Property of the Feature as JSON. |
Response
| Field | Value | ||
|---|---|---|---|
| topic | <namespace>/<thingName>/things/<channel>/commands/modify |
||
| path | /features/<featureId>/desiredProperties/<desiredPropertyPath> |
||
| value | The created desired Property of the Feature as JSON. This field is not available, if the Property already existed. | ||
| status | code | ||
201 |
Success - the desired Property was created successfully. | ||
204 |
Success - the desired Property was modified successfully. |
Event
If the Feature desired Property already existed before the command was applied and it was thus overwritten by the command, a modified event will be emitted.
| Field | Value |
|---|---|
| topic | <namespace>/<thingName>/things/<channel>/events/modified |
| path | /features/<featureId>/desiredProperties/<desiredPropertyPath> |
| value | The modified desired Property of the Thing as JSON. |
Example: Modify a single Feature desired Property
If the Feature desired Property did not yet exist before the command was applied, a created event will be emitted.
| Field | Value |
|---|---|
| topic | <namespace>/<thingName>/things/<channel>/events/created |
| path | /features/<featureId>/desiredProperties/<desiredPropertyPath> |
| value | The created Property of the Thing as JSON. |