# Create or modify all features of a specific thing at once

`PUT /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
         }
       }
     }
}
```

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

- `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 HTTP response, e.g. `If-Match: "hash:a75ece4e"`
  * 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

- `if-equal` (header, string, optional) - 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.
  Type: string
  
  enum: ["update","skip","skip-minimizing-merge"]

- `requested-acks` (query, string, optional) - 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.
  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

- `response-required` (query, boolean, optional) - 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`.
  Type: boolean

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

Request body: application/json (required)

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

Type: Features

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

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

Additional properties: 
  Reference: [Feature](https://sourcey-ditto.pages.dev/http-api-doc/models/feature.md); Type: Feature

```json
{
  "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
      }
    }
  }
}
```

Responses:

- 201: The features were successfully created.

Content type: application/json

Type: Features

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

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

Additional properties: 
  Reference: [Feature](https://sourcey-ditto.pages.dev/http-api-doc/models/feature.md); Type: Feature

```json
{}
```

- 204: The features were successfully modified.

- 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)).
  * the JSON body of the feature to be created/modified 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

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

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

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

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

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

Content type: application/json

Type: any

Example:

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

- `acknowledgementLabel1` (optional)
  Type: any
  
  Example:
  
  ```json
  {
    "status": 200,
    "payload": "OK"
  }
  ```
  
  - `status` (required)
    Type: integer
    
    The HTTP status of the acknowledgement
  
  - `payload` (optional)
    Type: object | string | number | array | boolean
    
    The payload of the acknowledgement
    
    oneOf:
      Type: object
    
      Type: string
    
      Type: number
    
      Type: array
    
      Type: boolean

## Examples

### cURL

```bash
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
      }
    }
  }
}'
```

### JavaScript

```javascript
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();
```

### Python

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