List all desired properties of a feature

The ID of a thing needs to follow the namespaced entity ID notation (see Ditto documentation on namespaced entity IDs).

The ID of the feature - has to conform to RFC-3986 (URI)

Contains a comma-separated list of fields from the desiredProperties to be included in the returned JSON.

Selectable fields

Supports selecting arbitrary sub-fields as defined in the desiredProperties by using a comma-separated list:

• several desiredProperties paths can be passed as a comma-separated list of JSON pointers (RFC-6901)

  For example:

  • ?fields=temperature would select only temperature property value of desiredProperties (if present)
  • ?fields=temperature,humidity would select only temperature and humidity property values of desiredProperties (if present)

Supports selecting arbitrary sub-fields of objects by wrapping sub-fields inside parentheses ( ):

• a comma-separated list of sub-fields (a sub-field is a JSON pointer (RFC-6901) separated with /) to select

• sub-selectors can be used to request only specific sub-fields by placing expressions in parentheses ( ) after a selected subfield

  For example:

  • ?fields=location(longitude,latitude) would select the longitude and latitude value inside the location property of desiredProperties

Examples

• ?fields=temperature,humidity,location(longitude,latitude)

• ?fields=configuration,status(powerConsumption/watts)

The If-Match header which has to conform to RFC-7232 (Conditional Requests). Common usages are:

• optimistic locking by specifying the ETag from a previous HTTP response, e.g. If-Match: "hash:a75ece4e"
• retrieving or modifying a resource only if it already exists, e.g. If-Match: *

The If-None-Match header, which has to conform to RFC-7232 (Conditional Requests). A common usage scenario is to modify a resource only if it does not yet exist, thus to create it, by specifying If-None-Match: *.

The get-metadata header, which retrieves Metadata of the Thing.

Defines how long the backend should wait for completion of the request, e.g. applied when waiting for requested acknowledgements via the requested-acks param. Can be specified without unit (then seconds are assumed) or together with s, ms or m unit. Example: 42s, 1m.

The default (if omitted) and maximum timeout is 60s. A value of 0 applies fire and forget semantics for the command resulting in setting response-required=false.

Defines that the request should only be processed if the given condition is met. The condition can be specified using RQL syntax.

Examples

E.g. if the temperature is not 23.9 update it to 23.9:

• PUT /api/2/things/{thingId}/features/temperature/properties/value?condition=ne(features/temperature/properties/value,23.9)

  body: 23.9

Further example conditions:

• ?condition=eq(features/temperature/properties/unit,"Celsius")
• ?condition=ge(features/temperature/properties/lastModified,"2021-08-22T19:45:00Z")
• ?condition=gt(_modified,"2021-08-05T12:17:00Z")
• ?condition=exists(features/temperature/properties/value)
• ?condition=empty(features/temperature/properties/value)
• ?condition=and(gt(features/temperature/properties/value,18.5),lt(features/temperature/properties/value,25.2))
• ?condition=or(gt(features/temperature/properties/value,18.5),not(exists(features/temperature/properties/value))

Defines to which channel to route the command: twin (digital twin) or live (the device).

• If setting the channel parameter is omitted, the twin channel is set by default and the command is routed to the persisted representation of a thing in Eclipse Ditto.
• When using the live channel, the command/message is sent towards the device.

Defines that the request should fetch thing data via live channel if the given condition is met. The condition can be specified using RQL syntax.

Examples

• ?live-channel-condition=lt(_modified,"2021-12-24T12:23:42Z")

• ?live-channel-condition=ge(features/ConnectionStatus/properties/status/readyUntil,time:now)

Defines a strategy how to handle timeouts of a live response to a request sent via channel=live or with a matching live-channel-condition.

The desired properties were successfully retrieved.

The (sub-)resource has not been modified. This happens when you specified a If-None-Match header which matches the current ETag of the (sub-)resource.

The request could not be completed. Possible reasons:

• the thingId does not conform to the namespaced entity ID notation (see Ditto documentation on namespaced entity IDs).
• at least one of the defined query parameters is invalid.

The request could not be completed due to missing authentication.

The request could not be completed. The specified feature has no desired properties or the thing with the specified thingId or the feature with featureId was not found.

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. For read requests, this error may only happen for a failing If-Match header. In case of a failing If-None-Match header for a read request, status 304 will be returned instead.