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 ACL of the created Thing
must include at least one subject authorized to READ, WRITE and ADMINISTRATE permissions.
If no ACL is provided within the command, a default ACL 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. | |
409 |
Conflict - a thing with the given ID already exists. | |
| See Thing Error Responses for examples of other error responses. |
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 update is targeting the ACL,
the authorized subject additionally needs ADMINISTRATE permission.
If the thing does not yet exist, the same rules apply as described for the create command.
Response
| Field | Value | |
|---|---|---|
| topic | <namespace>/<thingName>/things/<channel>/commands/modify |
|
| path | / |
|
| value | The created Thing as JSON object, see Ditto protocol payload (JSON). This field is not available, if the Thing already existed. | |
| status | code | |
201 |
Success - the Thing was created successfully. | |
204 |
Success - the Thing was modified successfully. | |
403 |
Not Modifiable - The Thing could not be modified as the requester had insufficient permissions (‘WRITE’ is required). | |
404 |
Not Found - The Thing was not found or requester had insufficient permissions. | |
| See Thing Error Responses for examples of other error responses. |
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. | |
403 |
Not Modifiable - The Attributes could not be modified as the requester had insufficient permissions (‘WRITE’ is required). | |
404 |
Not Found - The Thing or Attributes were not found or requester had insufficient permissions. | |
| See Thing Error Responses for examples of other error responses. |
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. | |
403 |
Not Modifiable - The Attribute could not be modified as the requester had insufficient permissions (‘WRITE’ is required). | |
404 |
Not Found - The Thing or Attribute was not found or requester had insufficient permissions. | |
| See Thing Error Responses for examples of other error responses. |
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. | |
403 |
Not Modifiable - The definition could not be modified as the requester had insufficient permissions (‘WRITE’ is required). | |
404 |
Not Found - The Thing or definition was not found or requester had insufficient permissions. | |
| See Thing Error Responses for examples of other error responses. |
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. | |
403 |
Not Modifiable - The Features could not be modified as the requester had insufficient permissions (‘WRITE’ is required). | |
404 |
Not Found - The Thing or Features were not found or requester had insufficient permissions. | |
| See Thing Error Responses for examples of other error responses. |
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. | |
403 |
Not Modifiable - The Feature could not be modified as the requester had insufficient permissions (‘WRITE’ is required). | |
404 |
Not Found - The Thing or Feature was not found or requester had insufficient permissions. | |
| See Thing Error Responses for examples of other error responses. |
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. | |
403 |
Not Modifiable - The Definition could not be modified as the requester had insufficient permissions (‘WRITE’ is required). | |
404 |
Not Found - The Thing, Feature or Definition was not found or requester had insufficient permissions. | |
| See Thing Error Responses for examples of other error responses. |
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. | |
403 |
Not Modifiable - The Properties could not be modified as the requester had insufficient permissions (‘WRITE’ is required). | |
404 |
Not Found - The Properties were not found or requester had insufficient permissions. | |
| See Thing Error Responses for examples of other error responses. |
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
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. | ||
403 |
Not Modifiable - The Property could not be modified as the requester had insufficient permissions (‘WRITE’ is required). | ||
404 |
Not Found - The Thing or Property was not found or requester had insufficient permissions. | ||
| See Thing Error Responses for examples of other error responses. |
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