Ditto Protocol topic structure for Things
A valid topic consists of six elements, describing the thing affected by this message and the type of the message:
<namespace>/<thingName>/things/<channel>/<criterion>/<action>
namespace
: the namespace of the Thing.thingName
: the name of the Thing.group
: the appropriate group for addressing Things isthings
.channel
: the channel of the Protocol message; can either belive
ortwin
.criterion
: the type of Protocol message; can either becommands
,events
,search
ormessages
.action
: the action executed on the Thing, only required for:- Commands:
create/modify
,merge
,retrieve
ordelete
. - Events:
created
,modified
,merged
,deleted.
- Commands:
Thing representation
The representation of a Thing
in API version 2 is specified as follows:
Commands
The following Thing commands are available:
Common errors to commands
Each Thing command could also result in an error response.
The "topic"
of such errors differ from the command "topic"
- correlation is however possible via the
"correlation-id"
header which is preserved in the error message.
The following table contains common error codes for Thing commands:
status | Value |
---|---|
400 |
Bad Format - The request could not be completed due to malformed request syntax. |
401 |
Unauthorized - The request could not be completed due to missing authentication. |
403 |
Forbidden - The Thing could not be modified as the requester had insufficient permissions (‘WRITE’ is required). |
404 |
Not Found - The request could not be completed. The Thing with the given ID was not found in the context of the authenticated user. |
412 |
Precondition Failed - A precondition for reading or writing the (sub-)resource failed. This will happen for write requests, if you specified an If-Match or If-None-Match header, which fails the precondition check against the current ETag of the (sub-)resource. |
413 |
Request Entity Too Large - The created or modified entity is larger than the configured limit (defaults to 100 kB). |
429 |
Too many modifying requests are already outstanding to a specific Thing. |