Features

Create or modify all features of a specific thing at once

PUT

https://ditto.eclipseprojects.io/api/2/things/{thingId}/features

Create or modify all features of a thing identified by the thingId path parameter.

Create all features at once

In case at the initial creation of your thing you have not specified any features, these can be created here.

Update all features at once

To update all features at once prepare the JSON body accordingly.

Note: In contrast to the "PUT thing" request, a partial update is not supported here, but the content will be overwritten. If you need to update single features or their paths, please use the sub-resources instead.

Example:

{
     "coffee-brewer": {
       "definition": ["com.acme:coffeebrewer:0.1.0"],
       "properties": {
         "brewed-coffees": 0
       }
     },
     "water-tank": {
       "properties": {
         "configuration": {
           "smartMode": true,
           "brewingTemp": 87,
           "tempToHold": 44,
           "timeoutSeconds": 6000
         },
         "status": {
           "waterAmount": 731,
           "temperature": 44
         }
       }
     }
}

Create or modify all features of a specific thing at once

curl -X PUT 'https://ditto.eclipseprojects.io/api/2/things/string/features' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "coffee-brewer": {
    "properties": {
      "definition": [
        "com.acme:coffeebrewer:0.1.0"
      ],
      "brewed-coffees": 0
    }
  },
  "water-tank": {
    "properties": {
      "configuration": {
        "smartMode": true,
        "brewingTemp": 87,
        "tempToHold": 44,
        "timeoutSeconds": 6000
      },
      "status": {
        "waterAmount": 731,
        "temperature": 44
      }
    }
  }
}'

const body = `{
  "coffee-brewer": {
    "properties": {
      "definition": [
        "com.acme:coffeebrewer:0.1.0"
      ],
      "brewed-coffees": 0
    }
  },
  "water-tank": {
    "properties": {
      "configuration": {
        "smartMode": true,
        "brewingTemp": 87,
        "tempToHold": 44,
        "timeoutSeconds": 6000
      },
      "status": {
        "waterAmount": 731,
        "temperature": 44
      }
    }
  }
}`;

const response = await fetch('https://ditto.eclipseprojects.io/api/2/things/string/features', {
  method: 'PUT',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();

import requests

body = '''{
  "coffee-brewer": {
    "properties": {
      "definition": [
        "com.acme:coffeebrewer:0.1.0"
      ],
      "brewed-coffees": 0
    }
  },
  "water-tank": {
    "properties": {
      "configuration": {
        "smartMode": true,
        "brewingTemp": 87,
        "tempToHold": 44,
        "timeoutSeconds": 6000
      },
      "status": {
        "waterAmount": 731,
        "temperature": 44
      }
    }
  }
}'''

response = requests.put(
    'https://ditto.eclipseprojects.io/api/2/things/string/features',
    data=body.encode('utf-8'),
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json',
    },
)
print(response.text)

Request Body

{
  "coffee-brewer": {
    "properties": {
      "definition": [
        "com.acme:coffeebrewer:0.1.0"
      ],
      "brewed-coffees": 0
    }
  },
  "water-tank": {
    "properties": {
      "configuration": {
        "smartMode": true,
        "brewingTemp": 87,
        "tempToHold": 44,
        "timeoutSeconds": 6000
      },
      "status": {
        "waterAmount": 731,
        "temperature": 44
      }
    }
  }
}

{}

{
  "status": 0,
  "error": "string",
  "message": "string",
  "description": "string",
  "href": "string"
}

{
  "status": 0,
  "error": "string",
  "message": "string",
  "description": "string",
  "href": "string"
}

{
  "status": 0,
  "error": "string",
  "message": "string",
  "description": "string",
  "href": "string"
}

{
  "status": 0,
  "error": "string",
  "message": "string",
  "description": "string",
  "href": "string"
}

{
  "status": 0,
  "error": "string",
  "message": "string",
  "description": "string",
  "href": "string"
}

{
  "status": 0,
  "error": "string",
  "message": "string",
  "description": "string",
  "href": "string"
}

{
  "acknowledgementLabel1": {
    "status": 200,
    "payload": "OK"
  },
  "acknnowledgementLabelN": {
    "status": 403,
    "payload": "Forbidden"
  }
}

Body

application/json

JSON object of all features to be modified at once. Consider that the value has to be a JSON object or null.

Examples:

an empty object: {} - would just delete all old features
an empty feature: { "featureId": {} } - We strongly recommend to use a restricted set of characters for the featureId, as it might be needed for the (URL) path later.

Currently these identifiers should follow the pattern: [_a-zA-Z][_a-zA-Z0-9-]*
a nested object with multiple features as shown in the example value field

List of features where the key represents the featureId of each feature. The featureId key must be unique in the list.

[key: string]Feature

Show child attributes

definitionArray<string>

The definitions of a feature.

propertiesFeatureProperties

An arbitrary JSON object describing the properties of a feature.

desiredPropertiesFeatureDesiredProperties

An arbitrary JSON object describing the desired properties of a feature.

Parameters

thingIdstringrequiredpath

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

if-equalstringupdateskipskip-minimizing-mergeheader

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.

requested-acksstringquery

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.

timeoutstringquery

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.

response-requiredbooleanquery

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.

conditionstringquery

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))

channelstringtwinlivequery

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.

Response

201CreatedFeatures

The features were successfully created.

Response headers

Response fields application/json

List of features where the key represents the featureId of each feature. The featureId key must be unique in the list.

[key: string]Feature

Show child attributes

definitionArray<string>

The definitions of a feature.

propertiesFeatureProperties

An arbitrary JSON object describing the properties of a feature.

desiredPropertiesFeatureDesiredProperties

An arbitrary JSON object describing the desired properties of a feature.

204No Content

The features were successfully modified.

Response headers

400Bad RequestAdvancedError

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 of the feature to be created/modified is invalid

Response fields application/json

statusintegerrequired

The HTTP status of the error

errorstringrequired

The error code of the occurred exception

messagestringrequired

The message of the error - what went wrong

descriptionstring

A description how to fix the error or more details

hrefstring

A link to further information about the error and how to fix it

401UnauthorizedAdvancedError

The request could not be completed due to missing authentication.

Response fields application/json

statusintegerrequired

The HTTP status of the error

errorstringrequired

The error code of the occurred exception

messagestringrequired

The message of the error - what went wrong

descriptionstring

A description how to fix the error or more details

hrefstring

A link to further information about the error and how to fix it

403ForbiddenAdvancedError

The request could not be completed. Possible reasons:

the caller has insufficient permissions. For modifying all features of an existing thing, WRITE permission is required.

Response fields application/json

statusintegerrequired

The HTTP status of the error

errorstringrequired

The error code of the occurred exception

messagestringrequired

The message of the error - what went wrong

descriptionstring

A description how to fix the error or more details

hrefstring

A link to further information about the error and how to fix it

404Not FoundAdvancedError

The request could not be completed. The thing with the given ID was not found.

Response fields application/json

statusintegerrequired

The HTTP status of the error

errorstringrequired

The error code of the occurred exception

messagestringrequired

The message of the error - what went wrong

descriptionstring

A description how to fix the error or more details

hrefstring

A link to further information about the error and how to fix it

412Precondition FailedAdvancedError

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.

Response headers

Response fields application/json

statusintegerrequired

The HTTP status of the error

errorstringrequired

The error code of the occurred exception

messagestringrequired

The message of the error - what went wrong

descriptionstring

A description how to fix the error or more details

hrefstring

A link to further information about the error and how to fix it

413Payload Too LargeAdvancedError

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

Response fields application/json

statusintegerrequired

The HTTP status of the error

errorstringrequired

The error code of the occurred exception

messagestringrequired

The message of the error - what went wrong

descriptionstring

A description how to fix the error or more details

hrefstring

A link to further information about the error and how to fix it

424any

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

Response fields application/json

acknowledgementLabel1any

Show child attributes

statusintegerrequired

The HTTP status of the acknowledgement

payloadobject | string | number | array | boolean

The payload of the acknowledgement

Show child attributes

One of

object

string

number

array

boolean

Example

{
  "status": 200,
  "payload": "OK"
}

Example

{
  "acknowledgementLabel1": {
    "status": 200,
    "payload": "OK"
  },
  "acknnowledgementLabelN": {
    "status": 403,
    "payload": "Forbidden"
  }
}

Authorization

OpenIDConnectopenIdConnect

OpenID Connect Discovery URL. The placeholder is replaced by Swagger UI when configured.

NginxBasichttp (basic)

Eclipse Ditto sandbox demo user (demo1 ... demo9) + password (demo)

Bearerhttp (bearer)

A JSON Web Token issued by a supported OAuth 2.0 Identity Provider.

Docs by Sourcey