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>/<thingId>/things/<channel>/commands/create
path /
value The complete thing as JSON object, see Ditto protocol payload (JSON).

Response

Field   Value
topic   <namespace>/<thingId>/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>/<thingId>/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>/<thingId>/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>/<thingId>/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>/<thingId>/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>/<thingId>/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>/<thingId>/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>/<thingId>/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>/<thingId>/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>/<thingId>/things/<channel>/commands/modify
path /attributes/<attributePath>
value The specific attribute of the Thing as JSON.

Response

Field   Value
topic   <namespace>/<thingId>/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>/<thingId>/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>/<thingId>/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 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>/<thingId>/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>/<thingId>/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>/<thingId>/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>/<thingId>/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>/<thingId>/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>/<thingId>/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>/<thingId>/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>/<thingId>/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>/<thingId>/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>/<thingId>/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>/<thingId>/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>/<thingId>/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>/<thingId>/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>/<thingId>/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>/<thingId>/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>/<thingId>/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>/<thingId>/things/<channel>/commands/modify
path /features/<featureId>/properties/<propertyPath>
value The specific Property of the Feature as JSON.

Response

Field   Value  
topic   <namespace>/<thingId>/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>/<thingId>/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>/<thingId>/things/<channel>/events/created
path /features/<featureId>/properties/<propertyPath>
value The created Property of the Thing as JSON.

Example: Create a single Feature Property

Tags: protocol