# Retrieve WoT Thing Directory

`GET /.well-known/wot`

Returns a WoT (Web of Things) Thing Description of the Ditto Thing Directory,
as specified by the [WoT Discovery](https://www.w3.org/TR/wot-discovery/) specification.

By default, this endpoint is publicly accessible without authentication. This can be configured
via the `GATEWAY_WOT_DIRECTORY_AUTHENTICATION_REQUIRED` environment variable.

Both `GET` and `HEAD` methods are supported per the WoT Discovery specification.

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.

Responses:

- 200: The WoT Thing Directory description was successfully retrieved.

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

```json
{
  "@context": [
    "https://www.w3.org/2022/wot/td/v1.1",
    "https://www.w3.org/2022/wot/discovery"
  ],
  "@type": "ThingDirectory",
  "id": "urn:ditto:wot:thing-directory",
  "title": "Thing Description Directory (TDD) of Eclipse Ditto",
  "version": {
    "model": "1.0.0",
    "instance": "1.0.0"
  }
}
```

- 401: The request could not be completed due to missing authentication (when authentication is required).

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/.well-known/wot' \
  -H 'Authorization: Bearer YOUR_TOKEN'
```

### JavaScript

```javascript
const response = await fetch('https://ditto.eclipseprojects.io/.well-known/wot', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

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

### Python

```python
import requests

response = requests.get(
    'https://ditto.eclipseprojects.io/.well-known/wot',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)
```