Protocol specification for Things

The Things specification defines all Ditto Protocol commands, responses, and events for managing Things and their sub-resources (attributes, features, properties, definitions).

Topic structure for Things

A valid topic consists of six elements:

<namespace>/<thingName>/things/<channel>/<criterion>/<action>

1. namespace: the namespace of the Thing.
2. thingName: the name of the Thing.
3. group: always things.
4. channel: either live or twin.
5. criterion: commands, events, search, or messages.
6. action: depends on criterion – see sections below.

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

Thing representation

The JSON representation of a Thing in API version 2:

Common errors

Every Thing command can result in an error response. You correlate errors to commands via the correlation-id header.

Response and Event conventions

All commands produce a response and (for successful state changes) an event. Both use the same topic and path as the command, with the criterion set to events for events.

Response fields

Status codes by command type

Event fields

Events use the same path as the command. The value field always contains the affected resource (the full resource for create/modify, the merge patch for merge, omitted for delete).

Permissions

All modify, merge, and delete commands require WRITE permission on the targeted resource path. Retrieve commands require READ permission.

Create and modify commands

Create and modify commands use the modify or create action in the topic path. A modify command with path / creates the Thing if it does not exist, or replaces it if it does.

Create a Thing

Create a new Thing. The Policy must include at least one subject with READ and WRITE permissions. If you do not provide a Policy, Ditto creates a default Policy granting all permissions to the authorized subject.

Create or modify a Thing

If the Thing exists, replace it. If not, create it.

Create or modify Attributes

Replace all Attributes of a Thing.

Create or modify a single Attribute

Create or update a specific attribute. Use JSON Pointer (RFC-6901) notation for the path.

Create or modify a Definition

Create or update the Thing’s definition.

Create or modify all Features

Replace all Features of a Thing.

Create or modify a single Feature

Create or update a specific Feature identified by <featureId>.

Create or modify a Feature Definition

Create or modify Feature Properties

Replace all Properties of a Feature.

Create or modify a single Feature Property

Use JSON Pointer (RFC-6901) to address nested properties.

Create or modify desired Properties

Replace all desired Properties of a Feature.

Create or modify a single desired Property

Merge commands

Merge commands use JSON Merge Patch (RFC-7396) to partially update a Thing or its sub-resources. In case of conflicts, the patch value overwrites the existing value. Setting a field to null removes it.

Merge a Thing

Apply a JSON Merge Patch to the entire Thing. Creates the Thing if it does not exist.

Merge Attributes

Merge a single Attribute

Merge the Definition

Merge the Policy ID

Response: 204.

Merge all Features

Merge a single Feature

Merge a Feature Definition

Merge Feature Properties

Merge a single Feature Property

Merge desired Properties

Merge a single desired Property

Retrieve commands

Retrieve commands read the current state of a Thing or its sub-resources. Use the optional fields parameter to select specific fields.

Retrieve a Thing

Retrieve multiple Things

Use the placeholder _ for <thingName> in the topic. Specify the Thing IDs in the value.

Retrieve Attributes

Retrieve a single Attribute

Retrieve the Definition

Retrieve all Features

Retrieve a single Feature

Retrieve a Feature Definition

Retrieve Feature Properties

Retrieve a single Feature Property

Retrieve desired Properties

Retrieve a single desired Property

Delete commands

Delete commands remove a Thing or one of its sub-resources. All delete responses return status 204 on success.

Delete a Thing

Delete all Attributes

Delete a single Attribute

Delete the Definition

Delete all Features

Delete a single Feature

Delete a Feature Definition

Delete Feature Properties

Delete a single Feature Property

Delete desired Properties

Delete a single desired Property

Further reading

• Search protocol – searching across Things
• Messages protocol – sending custom messages to/from Things
• Acknowledgements – requesting delivery confirmation
• Protocol examples – complete message examples