Create or update the definition 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)

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 if-equal header can take the values 'update' (which is the default if omitted), 'skip' or 'skip-minimizing-merge'. If 'update' is defined, the entity will always be updated, even if it is equal before the update. If 'skip' is defined, the entity not be updated if it is equal before the update. In this case a 'Precondition Failed' 412 status is returned. If 'skip-minimizing-merge' is defined, the entity will not be updated if it is equal before the update. In this case a 'Precondition Failed' 412 status is returned. Additionally, merge/patch commands will be minimized to only the fields which actually changed, compared to the current state of the entity.

The put-metadata header, which sets Metadata information in the Thing.

The delete-metadata header, which deletes Metadata of the Thing.

Contains the "requested acknowledgements" for this modifying request as comma separated list. The HTTP call will block until all requested acknowledgements were aggregated or will time out based on the specified timeout parameter.

The default (if omitted) requested acks is requested-acks=twin-persisted which will block the HTTP call until the change was persited to the twin.

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 whether a response is required to the API call or not - if set to false the response will directly sent back with a status code of 202 (Accepted).

The default (if ommited) response is true.

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.

The definition was successfully created.

The definition was successfully updated.

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).
• the JSON body is invalid

The request could not be completed due to missing authentication.

The request could not be completed. Possible reasons:

• the caller has insufficient permissions. For modifying the definition of an existing feature, WRITE permission is required.

The request could not be completed. The thing or the feature with the given ID 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.

The created or modified entity is larger than the accepted limit of 100 kB.

One or more acknowledgement requests in the parameter requested-acks were not fulfilled.