# Retrieve visible things or things with specified IDs

`GET /api/2/things`

Returns all visible things or things passed in by the required parameter `ids`, which you (the authorized subject) are allowed to read.

Optionally, if you want to retrieve only some of the thing's fields, you can use the specific field selectors (see parameter `fields`) .

Tip: In order to formulate a `filter` which things to search for, take a look at the `/search` resource.

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:

- `ids` (query, string, optional) - Contains a comma-separated list of `thingId`s to retrieve in one single request.
  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

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

Responses:

- 200: The successfully completed request contains a list of the for the user available Things, or the Things asked for via the `ids` paramter.
The Things are sorted either by their ID, or in the same order as the Thing IDs were provided in the `ids` parameter.

Content type: application/json

Type: Array<Thing>

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

Content type: application/td+json

Type: Array<WotThingDescription>

Items:
  Reference: [WotThingDescription](https://sourcey-ditto.pages.dev/http-api-doc/models/wotthingdescription.md); Type: WotThingDescription
  
  A WoT Thing Description version 1.1

- 400: The request could not be completed. At least one of the defined query parameters was 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

- 414: The request could not be completed due to an URI length exceeding 8k characters.

## Examples

### cURL

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

### JavaScript

```javascript
const response = await fetch('https://ditto.eclipseprojects.io/api/2/things', {
  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',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)
```