Edit this page

All topics contain the <channel> which may be either twin or live.
For the meaning of those two channels see Protocol specification.

Retrieve a Thing

Retrieve the Thing specified by the <namespace> and <thingId> in the topic. The response includes all details about the Thing. Optionally you can use field selectors (see fields) to only get the specified fields.

Command

Field Value
topic <namespace>/<thingName>/things/<channel>/commands/retrieve
path /
fields Contains a comma separated list of fields to be included in the returned JSON.

Response

Field   Value
topic   <namespace>/<thingName>/things/<channel>/commands/retrieve
path   /
value   The found complete Thing as JSON object. See Ditto protocol payload (JSON).
status code  
  200 Success.

Example: Retrieve a Thing

Retrieve multiple Things

Retrieve the Things specified by the <namespace> in the topic and the thingIds specified in the value. Note that the <thingName> in this case contains the placeholder _. You can also omit the <namespace> by using the placeholder _. The response includes all details about the requested Things. Optionally you can use field selectors (see fields) to only get the specified fields.

Command

Field Value
topic <namespace>/_/things/<channel>/commands/retrieve
path /
value a field thingIds that contains a JSON array of Thing IDs.
fields Contains a comma separated list of fields to be included in the returned JSON.

Response

Field   Value
topic   <namespace>/_/things/<channel>/commands/retrieve
path   /
value   JSON Array of all found Things (as JSON object). See Ditto protocol payload (JSON).
status code  
  200 Success.

Example: Retrieve multiple Things

Retrieve all Attributes of a Thing

Retrieve the Attributes of a Thing identified by the <namespace> and <thingId> in the topic.

Command

Field Value
topic <namespace>/<thingName>/things/<channel>/commands/retrieve
path /attributes

Response

Field   Value
topic   <namespace>/<thingName>/things/<channel>/commands/retrieve
path   /attributes
value   The Attributes of the Thing as JSON, see property attributes of Things JSON schema. See Ditto protocol payload (JSON)
status code  
  200 Success.

Example: Retrieve Attributes

Retrieve a single Attributes of a Thing

Retrieve a specific Attribute identified by the <attributePath> of the Thing. The Attribute (JSON) can be referenced hierarchically by applying JSON Pointer notation (RFC-6901).

Command

Field Value
topic <namespace>/<thingName>/things/<channel>/commands/retrieve
path /attributes/<attributePath>

Response

Field   Value
topic   <namespace>/<thingName>/things/<channel>/commands/retrieve
path   /attributes/<attributePath>
value   The specific Attribute of the Thing as JSON.
status code  
  200 Success.

Example: Retrieve a single Attribute

Retrieve the definition of a Thing

Retrieve the Definition of the Thing.

Command

Field Value
topic <namespace>/<thingName>/things/<channel>/commands/retrieve
path /definition

Response

Field   Value
topic   <namespace>/<thingName>/things/<channel>/commands/retrieve
path   /definition
value   The specific Definition of the Thing as JSON.
status code  
  200 Success.

Example: Retrieve a single Attribute

Retrieve all Features of a Thing

Retrieve the Features of a Thing identified by identified by the <namespace> and the <thingId> in the topic.

Command

Field Value
topic <namespace>/<thingName>/things/<channel>/commands/retrieve
path /features

Response

Field   Value
topic   <namespace>/<thingName>/things/<channel>/commands/retrieve
path   /features
value   All Features of the Thing as JSON, see property features of Things JSON schema. See Ditto protocol payload (JSON).
status code  
  200 Success.

Example: Retrieve Features

Retrieve a single Feature of a Thing

Retrieve a specific Feature (identified by the <featureId> 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/retrieve
path /features/<featureId>

Response

Field   Value
topic   <namespace>/<thingName>/things/<channel>/commands/retrieve
path   /features/<featureId>
value   The specific Feature of the Thing as JSON. See Ditto protocol payload (JSON).
status code  
  200 Success.

Example: Retrieve a single Feature

Retrieve Definition of a Feature

Retrieve the Definition of a Feature (identified by the <featureId> 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/retrieve
path /features/<featureId>/definition

Response

Field   Value
topic   <namespace>/<thingName>/things/<channel>/commands/retrieve
path   /features/<featureId>/definition
value   The Definition of the Feature as JSON array, see property properties of Things JSON schema. See Ditto protocol payload (JSON).
status code  
  200 Success.

Example: Retrieve Feature Definition

Retrieve all Properties of a Feature

Retrieve all Properties of a Feature (identified by the <featureId> 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/retrieve
path /features/<featureId>/properties

Response

Field   Value
topic   <namespace>/<thingName>/things/<channel>/commands/retrieve
path   /features/<featureId>/properties
value   The Properties of the Feature as JSON, see property properties of Things JSON schema. See Ditto protocol payload (JSON).
status code  
  200 Success.

Example: Retrieve Feature Properties

Retrieve all desired Properties of a Feature

Retrieve all desired Properties of a Feature (identified by the <featureId> 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/retrieve
path /features/<featureId>/desiredProperties

Response

Field   Value
topic   <namespace>/<thingName>/things/<channel>/commands/retrieve
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).
status code  
  200 Success.

Example: Retrieve Feature Properties

Retrieve a single Property of a Feature

Retrieve the Property of the Feature identified by the <featureId> in the path. The Property (JSON) can be referenced hierarchically by applying JSON Pointer notation (RFC-6901).

Command

Field Value
topic <namespace>/<thingName>/things/<channel>/commands/retrieve
path /features/<featureId>/properties/<propertyPath>

Response

Field   Value
topic   <namespace>/<thingName>/things/<channel>/commands/retrieve
path   /features/<featureId>/properties/<propertyPath>
value   The specific Property of the Feature as JSON.
status code  
  200 Success.

Example: Retrieve a single Feature Property

Retrieve a single desired Property of a Feature

Retrieve the desired Property of the Feature identified by the <featureId> in the path. The Property (JSON) can be referenced hierarchically by applying JSON Pointer notation (RFC-6901).

Command

Field Value
topic <namespace>/<thingName>/things/<channel>/commands/retrieve
path /features/<featureId>/desiredProperties/<desiredPropertyPath>

Response

Field   Value
topic   <namespace>/<thingName>/things/<channel>/commands/retrieve
path   /features/<featureId>/desiredProperties/<desiredPropertyPath>
value   The specific desired Property of the Feature as JSON.
status code  
  200 Success.

Example: Retrieve a single Feature Property

Tags: protocol