# Create or update a thing with a specified ID

`PUT /api/2/things/{thingId}`

Create or update the thing specified by the `thingId` path parameter and the optional JSON body.

* If you set a new `thingId` in the path, a thing will be created.
* If you set an existing `thingId` in the path, the thing will be updated.


### Create a new thing
At the initial creation of a thing, only a valid `thingId` is required.
However, you can create a full-fledged thing all at once.

### Example:
To create a coffee maker thing, set the `thingId` in the path, e.g. to "com.acme.coffeemaker:BE-42"
and the body part, like in the following snippet.

```
 {
   "definition": "com.acme:coffeebrewer:0.1.0",
   "attributes": {
     "manufacturer": "ACME demo corp.",
     "location": "Berlin, main floor",
     "serialno": "42",
     "model": "Speaking coffee machine"
   },
   "features": {
     "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
         }
       }
     }
   }
  }
 ```
As the example does not set a policy in the request body, but the thing concept requires one,
the service will create a default policy. The default policy, has the exactly same id
as the thing, and grants ALL permissions to the authorized subject.

In case you need to associate the new thing to an already existing policy you can additionally
set a policy e.g. "policyId": "com.acme.coffeemaker:policy-1" as the first element in the body part.
Keep in mind, that you can also change the assignment to another policy anytime,
with a request on the sub-resource "PUT /things/{thingId}/policyId"

The field `_created` is filled automatically with the timestamp of the creation. The field is read-only and can
be retrieved later by explicitly selecting it or used in search filters.

### Update an existing thing

For updating an existing thing, the authorized subject needs **WRITE** permission on the thing's root resource.

The ID of a thing cannot be changed after creation. Any `thingId`
specified in the request body is therefore ignored.

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

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

- `put-metadata` (header, Array<object>, optional) - The `put-metadata` header, which sets Metadata information in the Thing.
  Type: Array<object>
  
  An array of objects containing metadata to apply.
  
  Items:
    Type: object
    
    Object containing a `key` where to apply the metadata and a `value` with the metadata value to apply.
    
    Additional properties: 
      Type: any
      
      - `key` (optional)
        Type: string
        
        The JsonPointer to set the metadata `value` to. May start with `*/<key>` in order to apply the metadata to all affected JSON leaves.
      
      - `value` (optional)
        Type: any
        
        The arbitrary JSON value to set as metadata.

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

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

JSON representation of the thing to be modified.

Type: NewThing

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

- `_policy` (optional)
  Type: Policy
  
  The initial policy to create for this thing. This will create a separate policy entity managed by resource `/policies/{thingId}`.
  
  
  Use the placeholder `{{ request:subjectId }}` in order to let the backend insert the authenticated subjectId of the HTTP request.
  
  allOf:
    Reference: [Policy](https://sourcey-ditto.pages.dev/http-api-doc/models/policy.md); Type: Policy
    
    Policy consisting of policy entries

- `_copyPolicyFrom` (optional)
  Type: string
  
  This field may contain
  * the policy ID of an existing policy.
  
    The policy is copied and used for this newly created thing. The
    caller needs to have READ and WRITE<sup>*</sup> access to the policy.
  * a placeholder reference to a thing in the format {{ ref:things/[thingId]/policyId }} where you need to
    replace [thingId] with a valid thing ID.
  
    The newly created thing will then obtain a copy of the policy of
    the referenced thing. The caller needs to have READ access to the thing and READ and WRITE<sup>*</sup>
    access to the policy of the thing.
  
  
  <sup>*</sup> The check for WRITE permission avoids locking yourself out of the newly created policy. You can
  bypass this check by setting the header `allowPolicyLockout` to `true`. Be aware that the authorized
  subject cannot modify the policy if you do not assign WRITE permission on the policy resource!
  
  If you want to specify a policy ID for the copied policy, use the policyId field.
  
  This field must not be used together with the field _policy. If you specify both _policy and _copyPolicyFrom
  this will lead to an error response.

- `policyId` (required)
  Type: string
  
  The policy ID used for controlling access to this thing. 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.

```json
{
  "definition": "com.acme:coffeebrewer:0.1.0",
  "attributes": {
    "manufacturer": "ACME demo corp.",
    "location": "Berlin, main floor",
    "serialno": "42",
    "model": "Speaking coffee machine"
  },
  "features": {
    "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
        }
      }
    }
  }
}
```

Responses:

- 201: The thing was successfully created.

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.

- 204: The thing was 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 thing to be created/modified is invalid
  * the JSON body of the thing to be created/modified contains a `thingId`
  which does not match the ID in the path

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 would not have access to the thing after creating it with the given policy
  * the caller has insufficient permissions.
    For modifying an existing thing, an unrestricted `WRITE` permission on the thing's root resource 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. Possible reasons:
  * the referenced thing does not exist.
  * the caller has insufficient permissions to read the referenced thing.
  * the policy that should be copied does not exist.
  * the caller has insufficient permissions to read the policy that should be copied.

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' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "definition": "com.acme:coffeebrewer:0.1.0",
  "attributes": {
    "manufacturer": "ACME demo corp.",
    "location": "Berlin, main floor",
    "serialno": "42",
    "model": "Speaking coffee machine"
  },
  "features": {
    "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
        }
      }
    }
  }
}'
```

### JavaScript

```javascript
const body = `{
  "definition": "com.acme:coffeebrewer:0.1.0",
  "attributes": {
    "manufacturer": "ACME demo corp.",
    "location": "Berlin, main floor",
    "serialno": "42",
    "model": "Speaking coffee machine"
  },
  "features": {
    "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
        }
      }
    }
  }
}`;

const response = await fetch('https://ditto.eclipseprojects.io/api/2/things/string', {
  method: 'PUT',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json',
  },
  body,
});

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

### Python

```python
import requests

body = '''{
  "definition": "com.acme:coffeebrewer:0.1.0",
  "attributes": {
    "manufacturer": "ACME demo corp.",
    "location": "Berlin, main floor",
    "serialno": "42",
    "model": "Speaking coffee machine"
  },
  "features": {
    "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
        }
      }
    }
  }
}'''

response = requests.put(
    'https://ditto.eclipseprojects.io/api/2/things/string',
    data=body.encode('utf-8'),
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json',
    },
)
print(response.text)
```