# Retrieve a specific thing

`GET /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.

Authentication (security requirement alternatives):

```json
[
  {
    "OpenIDConnect": []
  },
  {
    "NginxBasic": []
  },
  {
    "Bearer": []
  }
]
```

- OpenIDConnect: openIdConnect. OpenID Connect Discovery URL. The placeholder is replaced by Swagger UI when configured.
- NginxBasic: http (basic). Eclipse Ditto sandbox demo user (demo1 ... demo9) + password (demo)
- Bearer: http (bearer). A JSON Web Token issued by a supported OAuth 2.0 Identity Provider.

Parameters:

- `thingId` (path, string, required) - The ID of a thing needs to follow the namespaced entity ID notation (see [Ditto documentation on namespaced entity IDs](https://www.eclipse.dev/ditto/basic-namespaces-and-names.html#namespaced-id)).
  Type: string

- `fields` (query, string, optional) - 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`
  Type: string

- `If-Match` (header, string, optional) - 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: *`
  Type: string

- `If-None-Match` (header, string, optional) - 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: *`.
  Type: string

- `get-metadata` (header, string, optional) - The `get-metadata` header, which retrieves Metadata of the Thing.
  Type: string
  
  A string of comma separated JsonPointers to retrieve from the Metadata of the Thing.

- `timeout` (query, string, optional) - 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`.
  Type: string

- `condition` (query, string, optional) - 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))```
  Type: string

- `channel` (query, string, optional) - 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.
  Type: string
  
  enum: ["twin","live"]

- `live-channel-condition` (query, string, optional) - 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)```
  Type: string

- `live-channel-timeout-strategy` (query, any, optional) - 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.
  Type: any
  
  enum: ["fail","use-twin"]

Responses:

- 200: The request successfully returned the specific thing.

Content type: application/json

Type: Thing

Schema: [Thing](https://sourcey-ditto.pages.dev/http-api-doc/models/thing.md)

- `thingId` (required)
  Type: string
  
  Unique identifier representing the thing

- `policyId` (required)
  Type: string
  
  The ID of the policy which controls the access to this thing. policies are managed by resource `/policies/{policyId}`

- `definition` (optional)
  Reference: [Definition](https://sourcey-ditto.pages.dev/http-api-doc/models/definition.md); Type: Definition
  
  A single fully qualified identifier of a definition in the form '<namespace>:<name>:<version>' or a valid HTTP(s) URL
  
  pattern: "([_a-zA-Z0-9\\-.]+):([_a-zA-Z0-9\\-.]+):([_a-zA-Z0-9\\-.]+)"

- `attributes` (optional)
  Reference: [Attributes](https://sourcey-ditto.pages.dev/http-api-doc/models/attributes.md); Type: Attributes
  
  An arbitrary JSON object describing the attributes of a thing.

- `features` (optional)
  Reference: [Features](https://sourcey-ditto.pages.dev/http-api-doc/models/features.md); Type: Features
  
  List of features where the key represents the `featureId` of each feature.
  The `featureId` key must be unique in the list.

- `_revision` (optional)
  Type: string
  
  _(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.

- `_created` (optional)
  Type: string
  
  _(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.

- `_modified` (optional)
  Type: string
  
  _(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.

- `_metadata` (optional)
  Type: object
  
  _(read-only)_ The Metadata of the Thing. This field is not returned by default but must be selected explicitly.

Content type: application/td+json

Type: WotThingDescription

A WoT Thing Description version 1.1

Schema: [WotThingDescription](https://sourcey-ditto.pages.dev/http-api-doc/models/wotthingdescription.md)

- `@context` (required)
  Type: Array<string> | string
  
  Example:
  
  ```json
  [
    "https://www.w3.org/2022/wot/td/v1.1"
  ]
  ```
  
  oneOf:
    Type: Array<string>
    
    Items:
      Type: string
      
      enum: ["https://www.w3.org/2019/wot/td/v1","http://www.w3.org/ns/td","https://www.w3.org/2022/wot/td/v1.1"]
  
    Type: string
    
    enum: ["https://www.w3.org/2019/wot/td/v1","http://www.w3.org/ns/td","https://www.w3.org/2022/wot/td/v1.1"]

- `title` (required)
  Type: string
  
  Example:
  
  ```json
  "My fancy Thing"
  ```

- `titles` (optional)
  Type: object
  
  Additional properties: 
    Type: string

- `description` (optional)
  Type: string
  
  Example:
  
  ```json
  "Does fancy stuff with IoT"
  ```

- `descriptions` (optional)
  Type: object
  
  Additional properties: 
    Type: string

- `@type` (optional)
  Type: string | Array<string>
  
  Example:
  
  ```json
  "Thing"
  ```
  
  oneOf:
    Type: string
  
    Type: Array<string>
    
    Items:
      Type: string

- `id` (optional)
  Type: string
  
  Example:
  
  ```json
  "urn:org.eclipse.ditto:my-fancy-thing"
  ```

- `base` (optional)
  Type: string, iri-reference
  
  Example:
  
  ```json
  "https://ditto.eclipseprojects.io/api/2/org.eclipse.ditto:my-fancy-thing"
  ```

- `version` (optional)
  Type: object
  
  Example:
  
  ```json
  {
    "model": "1.0.0",
    "instance": "1.0.0"
  }
  ```
  
  - `model` (optional)
    Type: string
  
  - `instance` (required)
    Type: string

- `links` (optional)
  Type: Array<object>
  
  Items:
    Type: object
    
    - `href` (required)
      Type: string, iri-reference
    
    - `rel` (optional)
      Type: string
    
    - `type` (optional)
      Type: string
    
    - `anchor` (optional)
      Type: string
    
    Additional properties: true

- `security` (required)
  Type: string | Array<string>
  
  Example:
  
  ```json
  "basic_sc"
  ```
  
  oneOf:
    Type: string
  
    Type: Array<string>
    
    Items:
      Type: string

- `securityDefinitions` (required)
  Type: object
  
  Example:
  
  ```json
  {
    "basic_sc": {
      "in": "header",
      "scheme": "basic"
    }
  }
  ```
  
  Additional properties: 
    Type: object

- `support` (optional)
  Type: string, iri-reference
  
  Example:
  
  ```json
  "https://www.eclipse.dev/ditto/"
  ```

- `created` (optional)
  Type: string, date-time

- `modified` (optional)
  Type: string, date-time

- `forms` (optional)
  Type: Array<object>
  
  Items:
    Type: object
    
    - `op` (optional)
      Type: string
    
    - `href` (optional)
      Type: string
    
    - `htv:methodName` (optional)
      Type: string
    
    - `contentType` (optional)
      Type: string
    
    - `additionalResponses` (optional)
      Type: Array<object>
      
      Items:
        Type: object
        
        - `success` (optional)
          Type: boolean
        
        - `schema` (optional)
          Type: string

- `properties` (optional)
  Type: object
  
  Additional properties: 
    Type: object

- `actions` (optional)
  Type: object
  
  Additional properties: 
    Type: object

- `events` (optional)
  Type: object
  
  Additional properties: 
    Type: object

- `uriVariables` (optional)
  Type: object
  
  Additional properties: 
    Type: object

- `schemaDefinitions` (optional)
  Type: object
  
  Additional properties: 
    Type: object

- `profile` (optional)
  Type: Array<string> | string
  
  oneOf:
    Type: Array<string>
    
    Items:
      Type: string, iri-reference
  
    Type: string, iri-reference

Additional properties: true

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

- 400: 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](https://www.eclipse.dev/ditto/basic-namespaces-and-names.html#namespaced-id))
  * at least one of the defined query parameters is invalid

Content type: application/json

Type: AdvancedError

Schema: [AdvancedError](https://sourcey-ditto.pages.dev/http-api-doc/models/advancederror.md)

- `status` (required)
  Type: integer
  
  The HTTP status of the error

- `error` (required)
  Type: string
  
  The error code of the occurred exception

- `message` (required)
  Type: string
  
  The message of the error - what went wrong

- `description` (optional)
  Type: string
  
  A description how to fix the error or more details

- `href` (optional)
  Type: string
  
  A link to further information about the error and how to fix it

- 401: The request could not be completed due to missing authentication.

Content type: application/json

Type: AdvancedError

Schema: [AdvancedError](https://sourcey-ditto.pages.dev/http-api-doc/models/advancederror.md)

- `status` (required)
  Type: integer
  
  The HTTP status of the error

- `error` (required)
  Type: string
  
  The error code of the occurred exception

- `message` (required)
  Type: string
  
  The message of the error - what went wrong

- `description` (optional)
  Type: string
  
  A description how to fix the error or more details

- `href` (optional)
  Type: string
  
  A link to further information about the error and how to fix it

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

Content type: application/json

Type: AdvancedError

Schema: [AdvancedError](https://sourcey-ditto.pages.dev/http-api-doc/models/advancederror.md)

- `status` (required)
  Type: integer
  
  The HTTP status of the error

- `error` (required)
  Type: string
  
  The error code of the occurred exception

- `message` (required)
  Type: string
  
  The message of the error - what went wrong

- `description` (optional)
  Type: string
  
  A description how to fix the error or more details

- `href` (optional)
  Type: string
  
  A link to further information about the error and how to fix it

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

Content type: application/json

Type: AdvancedError

Schema: [AdvancedError](https://sourcey-ditto.pages.dev/http-api-doc/models/advancederror.md)

- `status` (required)
  Type: integer
  
  The HTTP status of the error

- `error` (required)
  Type: string
  
  The error code of the occurred exception

- `message` (required)
  Type: string
  
  The message of the error - what went wrong

- `description` (optional)
  Type: string
  
  A description how to fix the error or more details

- `href` (optional)
  Type: string
  
  A link to further information about the error and how to fix it

## Examples

### cURL

```bash
curl -X GET 'https://ditto.eclipseprojects.io/api/2/things/string' \
  -H 'Authorization: Bearer YOUR_TOKEN'
```

### JavaScript

```javascript
const response = await fetch('https://ditto.eclipseprojects.io/api/2/things/string', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();
```

### Python

```python
import requests

response = requests.get(
    'https://ditto.eclipseprojects.io/api/2/things/string',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)
```