Things

Retrieve a specific thing

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

Returns the thing identified by the thingId path parameter. The response includes details about the thing, including the policyId, attributes, definition and features.

Optionally, you can use the field selectors (see parameter fields) to only get specific fields, which you are interested in.

Example:

Use the field selector _policy to retrieve the content of the policy.

Parameters

thingIdstringrequiredpath

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

fieldsstringquery

Contains a comma-separated list of fields to be included in the returned JSON. attributes can be selected in the same manner.

Selectable fields

  • thingId

  • policyId

  • definition

  • attributes

    Supports selecting arbitrary sub-fields by using a comma-separated list:

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

      For example:

      • ?fields=attributes/model would select only model attribute value (if present)
      • ?fields=attributes/model,attributes/location would select only model and location attribute values (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=attributes(model,location) would select only model and location attribute values (if present)
      • ?fields=attributes(coffeemaker/serialno) would select the serialno value inside the coffeemaker object
      • ?fields=attributes/address/postal(city,street) would select the city and street values inside the postal object inside the address object

  • features

    Supports selecting arbitrary fields in features similar to attributes (see also features documentation for more details)

  • _namespace

    Specifically selects the namespace also contained in the thingId

  • _revision

    Specifically selects the revision of the thing. The revision is a counter, which is incremented on each modification of a thing.

  • _created

    Specifically selects the created timestamp of the thing in ISO-8601 UTC format. The timestamp is set on creation of a thing.

  • _modified

    Specifically selects the modified timestamp of the thing in ISO-8601 UTC format. The timestamp is set on each modification of a thing.

  • _metadata

    Specifically selects the Metadata of the thing. The content is a JSON object having the Thing's JSON structure with the difference that the JSON leaves of the Thing are JSON objects containing the metadata.

  • _policy

    Specifically selects the content of the policy associated to the thing. (By default, only the policyId is returned.)

Examples

  • ?fields=thingId,attributes,features
  • ?fields=attributes(model,manufacturer),features
If-Matchstringheader

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 GET response, e.g. If-Match: "rev:4711"
  • retrieving or modifying a resource only if it already exists, e.g. If-Match: *
If-None-Matchstringheader

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: *.

get-metadatastringheader

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

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.

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.

The option live is not available when a new thing should be created, only for updating an existing thing.

live-channel-conditionstringquery

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)

live-channel-timeout-strategyanyfailuse-twinquery

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.

Response

200OKThing

The request successfully returned the specific thing.

Response headers
ETagstringheader

The (current server-side) ETag for this (sub-)resource. For top-level resources it is in the format "rev:[revision]", for sub-resources it has the format "hash:[calculated-hash]".

live-channel-condition-matchedbooleanheader

Whether or not the live-channel-condition did match and the thing was retrieved from the device.

channelstringheader

The cannel which was used to retrieve the thing.

Response fields application/json
thingIdstringrequired

Unique identifier representing the thing

policyIdstringrequired

The ID of the policy which controls the access to this thing. policies are managed by resource /policies/{policyId}

definitionDefinition

A single fully qualified identifier of a definition in the form '::' or a valid HTTP(s) URL

attributesAttributes

An arbitrary JSON object describing the attributes of a thing.

featuresFeatures

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

Show child attributes
[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.

_revisionstring

(read-only) The revision is a counter which is incremented on each modification of a Thing. This field is not returned by default but must be selected explicitly.

_createdstring

(read-only) The created timestamp of the Thing in ISO-8601 UTC format. The timestamp is set on creation of a Thing. This field is not returned by default but must be selected explicitly.

_modifiedstring

(read-only) The modified timestamp of the Thing in ISO-8601 UTC format. The timestamp is set on each modification of a Thing. This field is not returned by default but must be selected explicitly.

_metadataobject

(read-only) The Metadata of the Thing. This field is not returned by default but must be selected explicitly.

Response fields application/td+json

A WoT Thing Description version 1.1

@contextArray<string> | stringrequired
Show child attributes
One of
Array<string>https://www.w3.org/2019/wot/td/v1http://www.w3.org/ns/tdhttps://www.w3.org/2022/wot/td/v1.1
stringhttps://www.w3.org/2019/wot/td/v1http://www.w3.org/ns/tdhttps://www.w3.org/2022/wot/td/v1.1
Example
[
  "https://www.w3.org/2022/wot/td/v1.1"
]
titlestringrequired
Example
My fancy Thing
titlesobject
Show child attributes
[key: string]string
descriptionstring
Example
Does fancy stuff with IoT
descriptionsobject
Show child attributes
[key: string]string
@typestring | Array<string>
Show child attributes
One of
string
Array<string>
Example
Thing
idstring
Example
urn:org.eclipse.ditto:my-fancy-thing
basestring<iri-reference>
Example
https://ditto.eclipseprojects.io/api/2/org.eclipse.ditto:my-fancy-thing
versionobject
Show child attributes
modelstring
instancestringrequired
Example
{
  "model": "1.0.0",
  "instance": "1.0.0"
}
securitystring | Array<string>required
Show child attributes
One of
string
Array<string>
Example
basic_sc
securityDefinitionsobjectrequired
Show child attributes
[key: string]object
Example
{
  "basic_sc": {
    "in": "header",
    "scheme": "basic"
  }
}
supportstring<iri-reference>
Example
https://www.eclipse.dev/ditto/
createdstring<date-time>
modifiedstring<date-time>
formsArray<object>
Show child attributes
opstring
hrefstring
htv:methodNamestring
contentTypestring
additionalResponsesArray<object>
Show child attributes
successboolean
schemastring
propertiesobject
Show child attributes
[key: string]object
actionsobject
Show child attributes
[key: string]object
eventsobject
Show child attributes
[key: string]object
uriVariablesobject
Show child attributes
[key: string]object
schemaDefinitionsobject
Show child attributes
[key: string]object
profileArray<string> | string
Show child attributes
One of
Array<string>
string<iri-reference>
304Not Modified

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.

Response headers
ETagstringheader

The (current server-side) ETag for this (sub-)resource. For top-level resources it is in the format "rev:[revision]", for sub-resources it has the format "hash:[calculated-hash]".

400Bad RequestAdvancedError

The request could not be completed. Possible reasons:

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

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
ETagstringheader

The (current server-side) ETag for this (sub-)resource. For top-level resources it is in the format "rev:[revision]", for sub-resources it has the format "hash:[calculated-hash]".

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

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
↑↓ navigate↵ selectesc close