Ditto’s HTTP API is documented separately in the HTTP API Doc.
There you can explore the two different API versions (the difference is described in the Basic Overview).
Ditto does not provide a fully compliant RESTful API in the academic sense as it does not include hyperlinks in the HTTP responses. It however tries to follow the other best practices.
If you have any feedback on how to improve at that point, Ditto’s developer team is eager to learn.
Channel
Ditto supports two types of communication channels: twin and live.
The twin channel is used to communicate with the persisted digital twin representation of a device.
The live channel can be used to communicate directly with an actual device.
In case the live channel is used, the device itself is responsible for answering the command/message.
If no response is returned, the request will result in a timeout, and Ditto will respond with 408 Request Timeout.
This timeout can be set with the timeout parameter. If no timeout parameter is set, the default of 10s is used to
wait for response of the device.
When routing live commands to devices, Ditto is doing an authorization check based on the policy
of the thing. Ditto also filters responses based on that policy.
Ditto ensures that the response from the device contains the same correlation ID, entity ID and path.
For the device it is necessary to send back the correlating command response type for the send command. In case there is
a mismatch of the command and command response type Ditto will drop the response from the device and the request will
result in a timeout.
The default channel for all HTTP requests is the twin channel. The channel can either be set via HTTP header or via
query parameter.
For more information about the channel concept see section Ditto Protocol > Protocol twin/live channel.
Content Type
Currently, the content-type application/json is supported for all REST resources except the PATCH resource.
There the content-type has to be application/merge-patch+json.