blob: 6d1bd4e27869449e5ea173ead1d9e3f87b3da20e [file] [log] [blame]
openapi: 3.0.0
info:
title: Eclipse Ditto HTTP API
version: '2'
description: |-
JSON-based, REST-like API for Eclipse Ditto
The Eclipse Ditto HTTP API uses response status codes (see [RFC 7231](https://tools.ietf.org/html/rfc7231#section-6))
to indicate whether a specific request has been successfully completed, or not.
However, the descriptions we provide additionally to the status code (e.g. in our API docs, or error codes like. "things.entitiy.tooLarge") might change without advance notice. These are not be considered as official API, and must therefore not be applied in your applications or tests.
servers:
- url: 'https://ditto.eclipseprojects.io/api/2'
description: online Ditto Sandbox
- url: /api/2
description: local Ditto
tags:
- name: Things
description: Manage every thing
- name: Features
description: Structure the features of your things
- name: Policies
description: Control access to your things
- name: Things-Search
description: Find every thing
- name: Messages
description: Talk with your things
security:
- basicAuth: []
- bearerAuth: []
paths:
/things:
get:
summary: Retrieve multiple things with specified IDs
description: |-
Returns all 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: If you don't know the thing IDs, start with the search resource.
tags:
- Things
parameters:
- name: ids
in: query
description: |-
Contains a comma-separated list of `thingId`s to retrieve in one
single request.
required: true
schema:
type: string
- $ref: '#/components/parameters/ThingFieldsQueryParam'
- $ref: '#/components/parameters/TimeoutParam'
responses:
'200':
description: |-
The successfully completed request contains as its result the first 200 for the user available Things.
The Things are sorted in the same order as the Thing IDs were provided in the `ids` parameter.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Thing'
'400':
description: |-
The request could not be completed. At least one of the defined
query parameters was invalid.
content:
application/json:
schema:
$ref: '#/components/schemas/AdvancedError'
'401':
description: The request could not be completed due to missing authentication.
content:
application/json:
schema:
$ref: '#/components/schemas/AdvancedError'
'414':
description: |-
The request could not be completed due to an URI length exceeding 8k
characters.
post:
summary: Create a new thing
description: |-
Creates a thing with a default `thingId` and a default `policyId`.
The thing will be empty, i.e. no features, definition, attributes etc. by default.
The default `thingId` consists of your default namespace and a UUID.
The default `policyId` is identical with the default `thingId`, and allows the currently authorized subject all permissions.
In case you need to create a thing with a specific ID, use a *PUT* request instead, as any `thingId` specified in the request body will be ignored.
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.
tags:
- Things
parameters:
- $ref: '#/components/parameters/RequestedAcksParam'
- $ref: '#/components/parameters/TimeoutParam'
- $ref: '#/components/parameters/ResponseRequiredParam'
- $ref: '#/components/parameters/AllowPolicyLockoutParam'
responses:
'201':
description: The thing was successfully created.
headers:
ETag:
description: |-
The (current server-side) ETag for this (sub-)resource. For top-level resources it is in the format
"rev:[revision]", for sub-resources it has the format "hash:[calculated-hash]".
schema:
type: string
Location:
description: The location of the created thing resource
schema:
type: string
content:
application/json:
schema:
$ref: '#/components/schemas/Thing'
'400':
description: |-
The request could not be completed. Possible reasons:
* the `thingId` must not be set in the request body
* the JSON body of the thing to be created is invalid
content:
application/json:
schema:
$ref: '#/components/schemas/AdvancedError'
'401':
description: The request could not be completed due to missing authentication.
content:
application/json:
schema:
$ref: '#/components/schemas/AdvancedError'
'403':
description: |-
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.
content:
application/json:
schema:
$ref: '#/components/schemas/AdvancedError'
'404':
description: |-
The request could not be completed. Possible reasons:
* the referenced thing does not exist.
* the caller had insufficient permissions to read the referenced thing.
* the policy that should be copied does not exist.
* the caller had insufficient permissions to read the policy that should be copied.
content:
application/json:
schema:
$ref: '#/components/schemas/AdvancedError'
'412':
$ref: '#/components/responses/PreconditionFailed'
'413':
$ref: '#/components/responses/EntityTooLarge'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/NewThing'
example:
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
description: 'JSON representation of the thing to be created. Use { } to create an empty thing with a default policy.'
'/things/{thingId}':
get:
summary: Retrieve a specific thing
description: |-
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.
tags:
- Things
parameters:
- $ref: '#/components/parameters/ThingIdPathParam'
- $ref: '#/components/parameters/ThingFieldsQueryParam'
- $ref: '#/components/parameters/IfMatchHeaderParam'
- $ref: '#/components/parameters/IfNoneMatchHeaderParam'
- $ref: '#/components/parameters/TimeoutParam'
responses:
'200':
description: The request successfully returned the specific thing.
headers:
ETag:
description: |-
The (current server-side) ETag for this (sub-)resource. For top-level resources it is in the format
"rev:[revision]", for sub-resources it has the format "hash:[calculated-hash]".
schema:
type: string
content:
application/json:
schema:
$ref: '#/components/schemas/Thing'
'304':
$ref: '#/components/responses/NotModified'
'400':
description: |-
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.org/ditto/basic-namespaces-and-names.html#namespaced-id))
* at least one of the defined query parameters is invalid
content:
application/json:
schema:
$ref: '#/components/schemas/AdvancedError'
'401':
description: The request could not be completed due to missing authentication.
content:
application/json:
schema:
$ref: '#/components/schemas/AdvancedError'
'404':
description: |-
The request could not be completed. The thing with the given ID was
not found.
content:
application/json:
schema:
$ref: '#/components/schemas/AdvancedError'
'412':
$ref: '#/components/responses/PreconditionFailed'
put:
summary: Create or update a thing with a specified ID
description: |-
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.
### Partially update an existing thing
When updating an existing thing, which already contains `attributes`, `definition` `policyId` or `features`,
the existing fields must not explicitly be provided again.
For this "PUT thing" request - and only for this top-level update on the thing -
the top-level field to update is **merged** with the existing top-level fields of the thing.
### Example for a partial update
Given, a thing already exists with this content:
```
{
"thingId": "namespace:thing-name",
"policyId": "namespace:policy-name",
"definition": "namespace:model:version",
"attributes": {
"foo": 1
},
"features": {...}
}
```
The thing's `attributes` may be modified without having to pass the `policyId` or
the `features` in again.
For updating the `attributes`, following request body would be sufficient :
```
{
"attributes": {
"foo": 2,
"bar": false
}
}
```
The `policyId` and `features` of the thing will not be overwritten.
The thing will be merged into:
```
{
"thingId": "namespace:thing-name",
"policyId": "namespace:policy-name",
"definition": "namespace:model:version",
"attributes": {
"foo": 2,
"bar": false
},
"features": {...}
}
```
tags:
- Things
parameters:
- $ref: '#/components/parameters/ThingIdPathParam'
- $ref: '#/components/parameters/IfMatchHeaderParam'
- $ref: '#/components/parameters/IfNoneMatchHeaderParam'
- $ref: '#/components/parameters/PutMetadataParam'
- $ref: '#/components/parameters/RequestedAcksParam'
- $ref: '#/components/parameters/TimeoutParam'
- $ref: '#/components/parameters/ResponseRequiredParam'
responses:
'201':
description: The thing was successfully created.
headers:
ETag:
description: |-
The (current server-side) ETag for this (sub-)resource. For top-level resources it is in the format
"rev:[revision]", for sub-resources it has the format "hash:[calculated-hash]".
schema:
type: string
Location:
description: The location of the created thing resource
schema:
type: string
content:
application/json:
schema:
$ref: '#/components/schemas/Thing'
'204':
description: The thing was successfully modified.
headers:
ETag:
description: |-
The (current server-side) ETag for this (sub-)resource. For top-level resources it is in the format
"rev:[revision]", for sub-resources it has the format "hash:[calculated-hash]".
schema:
type: string
'400':
description: |-
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.org/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:
application/json:
schema:
$ref: '#/components/schemas/AdvancedError'
'401':
description: The request could not be completed due to missing authentication.
content:
application/json:
schema:
$ref: '#/components/schemas/AdvancedError'
'403':
description: |-
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:
application/json:
schema:
$ref: '#/components/schemas/AdvancedError'
'404':
description: |-
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:
application/json:
schema:
$ref: '#/components/schemas/AdvancedError'
'412':
$ref: '#/components/responses/PreconditionFailed'
'413':
$ref: '#/components/responses/EntityTooLarge'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/NewThing'
example:
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
description: JSON representation of the thing to be modified.
delete:
summary: Delete a specific thing
description: |-
Deletes the thing identified by the `thingId` path parameter.
This will not delete the policy, which is used for controlling access to this thing.
You can delete the policy afterwards via DELETE `/policies/{policyId}` if you don't need it for other things.
tags:
- Things
parameters:
- $ref: '#/components/parameters/ThingIdPathParam'
- $ref: '#/components/parameters/IfMatchHeaderParam'
- $ref: '#/components/parameters/IfNoneMatchHeaderParam'
- $ref: '#/components/parameters/RequestedAcksParam'
- $ref: '#/components/parameters/TimeoutParam'
- $ref: '#/components/parameters/ResponseRequiredParam'
responses:
'204':
description: The thing was successfully deleted.
'400':
description: |-
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.org/ditto/basic-namespaces-and-names.html#namespaced-id)).
content:
application/json:
schema:
$ref: '#/components/schemas/AdvancedError'
'401':
description: The request could not be completed due to missing authentication.
content:
application/json:
schema:
$ref: '#/components/schemas/AdvancedError'
'403':
description: |-
The request could not be completed. Possible reasons:
* the caller had insufficient permissions.
For deleting an existing thing, an unrestricted `WRITE` permission on the thing's root resource is required.
content:
application/json:
schema:
$ref: '#/components/schemas/AdvancedError'
'404':
description: |-
The request could not be completed. The thing with the given ID was
not found.
content:
application/json:
schema:
$ref: '#/components/schemas/AdvancedError'
'412':
$ref: '#/components/responses/PreconditionFailed'
'/things/{thingId}/definition':
get:
summary: Retrieve the definition of a specific thing
description: Returns the definition of the thing identified by the `thingId` path parameter.
tags:
- Things
parameters:
- $ref: '#/components/parameters/ThingIdPathParam'
- $ref: '#/components/parameters/IfMatchHeaderParamHash'
- $ref: '#/components/parameters/IfNoneMatchHeaderParam'
- $ref: '#/components/parameters/TimeoutParam'
responses:
'200':
description: The request successfully returned the definition of the specific thing.
headers:
ETag:
description: |-
The (current server-side) ETag for this (sub-)resource. For top-level resources it is in the format
"rev:[revision]", for sub-resources it has the format "hash:[calculated-hash]".
schema:
type: string
content:
application/json:
schema:
$ref: '#/components/schemas/Definition'
'304':
$ref: '#/components/responses/NotModified'
'400':
description: |-
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.org/ditto/basic-namespaces-and-names.html#namespaced-id)).
content:
application/json:
schema:
$ref: '#/components/schemas/AdvancedError'
'401':
description: The request could not be completed due to missing authentication.
content:
application/json:
schema:
$ref: '#/components/schemas/AdvancedError'
'403':
description: |-
The request could not be completed. Possible reasons:
* the caller has insufficient permissions.
For modifying the definition of an existing thing, `WRITE` permission is required.
content:
application/json:
schema:
$ref: '#/components/schemas/AdvancedError'
'404':
description: |-
The request could not be completed. The thing with the given ID was
not found.
content:
application/json:
schema:
$ref: '#/components/schemas/AdvancedError'
'412':
$ref: '#/components/responses/PreconditionFailed'
put:
summary: Create or update the definition of a specific thing
description: |-
* If the thing does not have a definition yet, this request will create it.
* If the thing already has a definition you can assign it to a new one by setting the new definition in the request body.
tags:
- Things
parameters:
- $ref: '#/components/parameters/ThingIdPathParam'
- $ref: '#/components/parameters/IfMatchHeaderParamHash'
- $ref: '#/components/parameters/IfNoneMatchHeaderParam'
- $ref: '#/components/parameters/RequestedAcksParam'
- $ref: '#/components/parameters/TimeoutParam'
- $ref: '#/components/parameters/ResponseRequiredParam'
responses:
'201':
description: The definition was successfully created.
headers:
ETag:
description: |-
The (current server-side) ETag for this (sub-)resource. For top-level resources it is in the format
"rev:[revision]", for sub-resources it has the format "hash:[calculated-hash]".
schema:
type: string
Location:
description: The location of the created definition resource
schema:
type: string
content:
application/json:
schema:
$ref: '#/components/schemas/Definition'
'204':
description: The definition was successfully updated.
headers:
ETag:
description: |-
The (current server-side) ETag for this (sub-)resource. For top-level resources it is in the format
"rev:[revision]", for sub-resources it has the format "hash:[calculated-hash]".
schema:
type: string
'400':
description: |-
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.org/ditto/basic-namespaces-and-names.html#namespaced-id))
* the JSON was invalid
* the request body was not a JSON object.
content:
application/json:
schema:
$ref: '#/components/schemas/AdvancedError'
'401':
description: The request could not be completed due to missing authentication.
content:
application/json:
schema:
$ref: '#/components/schemas/AdvancedError'
'403':
description: |-
The request could not be completed. Possible reasons:
* the caller has insufficient permissions.
For modifying a definition of an existing thing, `WRITE` permission is required.
content:
application/json:
schema:
$ref: '#/components/schemas/AdvancedError'
'404':
description: |-
The request could not be completed. The thing with the given ID was
not found.
content:
application/json:
schema:
$ref: '#/components/schemas/AdvancedError'
'412':
$ref: '#/components/responses/PreconditionFailed'
'413':
$ref: '#/components/responses/EntityTooLarge'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/Definition'
example: '"example:test:definition"'
description: |-
JSON string of the definition to be modified. Consider that the
value has to be a JSON string or `null`, examples:
* an string: `{ ""value"}` -}. Currently the definition should follow the pattern: [_a-zA-Z0-9\-]:[_a-zA-Z0-9\-]:[_a-zA-Z0-9\-]
* an empty string: `""`
delete:
summary: Delete the definition of a specific thing
description: Deletes the definition of the thing identified by the `thingId`.
tags:
- Things
parameters:
- $ref: '#/components/parameters/ThingIdPathParam'
- $ref: '#/components/parameters/IfMatchHeaderParamHash'
- $ref: '#/components/parameters/IfNoneMatchHeaderParam'
- $ref: '#/components/parameters/RequestedAcksParam'
- $ref: '#/components/parameters/TimeoutParam'
- $ref: '#/components/parameters/ResponseRequiredParam'
responses:
'204':
description: The definition was successfully deleted.
'400':
description: |-
The request could not be completed. The `thingId` does not conform to the namespaced entity ID notation
(see [Ditto documentation on namespaced entity IDs](https://www.eclipse.org/ditto/basic-namespaces-and-names.html#namespaced-id)).
content:
application/json:
schema:
$ref: '#/components/schemas/AdvancedError'
'401':
description: The request could not be completed due to missing authentication.
content:
application/json:
schema:
$ref: '#/components/schemas/AdvancedError'
'403':
description: |-
The request could not be completed. Possible reasons:
* the caller has insufficient permissions.
For modifying a definition of an existing thing, `WRITE` permission is required.
content:
application/json:
schema:
$ref: '#/components/schemas/AdvancedError'
'404':
description: |-
The request could not be completed. The thing with the given ID or
its definition was not found.
content:
application/json:
schema:
$ref: '#/components/schemas/AdvancedError'
'412':
$ref: '#/components/responses/PreconditionFailed'
'/things/{thingId}/policyId':
get:
summary: Retrieve the policy ID of a thing
description: Returns the policy ID of the thing identified by the `thingId` path parameter.
tags:
- Things
parameters:
- $ref: '#/components/parameters/ThingIdPathParam'
- $ref: '#/components/parameters/IfMatchHeaderParamHash'
- $ref: '#/components/parameters/IfNoneMatchHeaderParam'
- $ref: '#/components/parameters/TimeoutParam'
responses:
'200':
description: The request successfully returned the policy ID.
headers:
ETag:
description: |-
The (current server-side) ETag for this (sub-)resource. For top-level resources it is in the format
"rev:[revision]", for sub-resources it has the format "hash:[calculated-hash]".
schema:
type: string
content:
application/json:
schema:
type: string
'304':
$ref: '#/components/responses/NotModified'
'400':
description: |-
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.org/ditto/basic-namespaces-and-names.html#namespaced-id)).
content:
application/json:
schema:
$ref: '#/components/schemas/AdvancedError'
'401':
description: The request could not be completed due to missing authentication.
content:
application/json:
schema:
$ref: '#/components/schemas/AdvancedError'
'404':
description: The request could not be completed. The thing with the given ID was not found in the context of the authenticated user.
content:
application/json:
schema:
$ref: '#/components/schemas/AdvancedError'
'412':
$ref: '#/components/responses/PreconditionFailed'
put:
summary: Create or update the policy ID of a thing
description: |-
Create or update the policy ID of the thing identified by the `thingId`
path parameter.
### Create
If the thing does not have a `policyId` yet, it is
considered to have been created via API version 1, where the access control list `acl`
mechanism is used. In that case, this request will create the `policyId`.
Note: You will need to create the policy content separately.
### Update
If the thing already has a `policyId` you can assign it to an existing policy by setting
the new `policyId` in the request body.
tags:
- Things
parameters:
- $ref: '#/components/parameters/ThingIdPathParam'
- $ref: '#/components/parameters/IfMatchHeaderParamHash'
- $ref: '#/components/parameters/IfNoneMatchHeaderParam'
- $ref: '#/components/parameters/RequestedAcksParam'
- $ref: '#/components/parameters/TimeoutParam'
- $ref: '#/components/parameters/ResponseRequiredParam'
responses:
'201':
description: 'The policy ID was successfully created. Note: You will need to create the policy content separately.'
headers:
ETag:
description: |-
The (current server-side) ETag for this (sub-)resource. For top-level resources it is in the format
"rev:[revision]", for sub-resources it has the format "hash:[calculated-hash]".
schema:
type: string
content:
application/json:
schema:
type: string
'204':
description: The policy ID was successfully updated.
headers:
ETag:
description: |-
The (current server-side) ETag for this (sub-)resource. For top-level resources it is in the format
"rev:[revision]", for sub-resources it has the format "hash:[calculated-hash]".
schema:
type: string
'400':
description: |-
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.org/ditto/basic-namespaces-and-names.html#namespaced-id))
content:
application/json:
schema:
$ref: '#/components/schemas/AdvancedError'
'401':
description: The request could not be completed due to missing authentication.
content:
application/json:
schema:
$ref: '#/components/schemas/AdvancedError'
'404':
description: |-
The request could not be completed. The thing with the given ID was
not found in the context of the authenticated user.
content:
application/json:
schema:
$ref: '#/components/schemas/AdvancedError'
'412':
$ref: '#/components/responses/PreconditionFailed'
'413':
$ref: '#/components/responses/EntityTooLarge'
requestBody:
content:
application/json:
schema:
type: string
example: '"your.namespace:your-policy-name"'
description: |-
The policy is used for controlling access to this thing. It is managed by
resource `/policies/{policyId}`.
The ID of a policy needs to conform to the namespaced entity ID notation (see [Ditto documentation on namespaced entity IDs](https://www.eclipse.org/ditto/basic-namespaces-and-names.html#namespaced-id)).
required: true
'/things/{thingId}/attributes':
get:
summary: List all attributes of a specific thing
description: Returns all attributes of the thing identified by the `thingId` path parameter.
tags:
- Things
parameters:
- $ref: '#/components/parameters/ThingIdPathParam'
- $ref: '#/components/parameters/AttributesFieldsQueryParam'
- $ref: '#/components/parameters/IfMatchHeaderParamHash'
- $ref: '#/components/parameters/IfNoneMatchHeaderParam'
- $ref: '#/components/parameters/TimeoutParam'
responses:
'200':
description: The attributes of the specific thing were successfully retrieved.
headers:
ETag:
description: |-
The (current server-side) ETag for this (sub-)resource. For top-level resources it is in the format
"rev:[revision]", for sub-resources it has the format "hash:[calculated-hash]".
schema:
type: string
content:
application/json:
schema:
$ref: '#/components/schemas/Attributes'
'304':
$ref: '#/components/responses/NotModified'
'400':
description: |-
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.org/ditto/basic-namespaces-and-names.html#namespaced-id))
content:
application/json:
schema:
$ref: '#/components/schemas/AdvancedError'
'401':
description: The request could not be completed due to missing authentication.
content:
application/json:
schema:
$ref: '#/components/schemas/AdvancedError'
'404':
description: The request could not be completed. The thing with the given ID was not found.
content:
application/json:
schema:
$ref: '#/components/schemas/AdvancedError'
'412':
$ref: '#/components/responses/PreconditionFailed'
put:
summary: Create or update all attributes of a specific thing at once
description: |-
Create or update the attributes of a thing identified by the `thingId`
path parameter. The attributes will be overwritten - all at once - with the
content (JSON) set in the request body.
tags:
- Things
parameters:
- $ref: '#/components/parameters/ThingIdPathParam'
- $ref: '#/components/parameters/IfMatchHeaderParamHash'
- $ref: '#/components/parameters/IfNoneMatchHeaderParam'
- $ref: '#/components/parameters/RequestedAcksParam'
- $ref: '#/components/parameters/TimeoutParam'
- $ref: '#/components/parameters/ResponseRequiredParam'
responses:
'201':
description: The attributes were successfully created.
headers:
ETag:
description: |-
The (current server-side) ETag for this (sub-)resource. For top-level resources it is in the format
"rev:[revision]", for sub-resources it has the format "hash:[calculated-hash]".
schema:
type: string
Location:
description: The location of the created attribute resource
schema:
type: string
content:
application/json:
schema:
$ref: '#/components/schemas/Attributes'
'204':
description: The attributes were successfully updated.
headers:
ETag:
description: |-
The (current server-side) ETag for this (sub-)resource. For top-level resources it is in the format
"rev:[revision]", for sub-resources it has the format "hash:[calculated-hash]".
schema:
type: string
'400':
description: |-
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.org/ditto/basic-namespaces-and-names.html#namespaced-id)).
* the JSON body of the attributes to be created/modified is invalid
content:
application/json:
schema:
$ref: '#/components/schemas/AdvancedError'
'401':
description: The request could not be completed due to missing authentication.
content:
application/json:
schema:
$ref: '#/components/schemas/AdvancedError'
'403':
description: |-
The request could not be completed. Possible reasons:
* the caller has insufficient permissions.
For modifying the attributes of an existing thing, `WRITE` permission is required.
content:
application/json:
schema:
$ref: '#/components/schemas/AdvancedError'
'404':
description: |-
The request could not be completed. The thing with the given ID was
not found.
content:
application/json:
schema:
$ref: '#/components/schemas/AdvancedError'
'412':
$ref: '#/components/responses/PreconditionFailed'
'413':
$ref: '#/components/responses/EntityTooLarge'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/Attributes'
example:
manufacturer:
name: ACME demo corp.
location: 'Berlin, main floor'
coffeemaker:
serialno: '42'
model: Speaking coffee machine
description: |-
JSON object of all attributes 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 attributes
* a simple object: `{ "key": "value"}` - We strongly recommend to use a restricted set of characters for the key (identifier), as the key might be needed for the (URL) path later.<br> Currently these identifiers should follow the pattern: [_a-zA-Z][_a-zA-Z0-9\-]*
* a nested object as shown in the example value
required: true
delete:
summary: Delete all attributes of a specific thing at once
description: |-
Deletes all attributes of the thing identified by the `thingId` path
parameter.
tags:
- Things
parameters:
- $ref: '#/components/parameters/ThingIdPathParam'
- $ref: '#/components/parameters/IfMatchHeaderParamHash'
- $ref: '#/components/parameters/IfNoneMatchHeaderParam'
- $ref: '#/components/parameters/RequestedAcksParam'
- $ref: '#/components/parameters/TimeoutParam'
- $ref: '#/components/parameters/ResponseRequiredParam'
responses:
'204':
description: The attributes were successfully deleted.
'400':
description: |-
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.org/ditto/basic-namespaces-and-names.html#namespaced-id)).
content:
application/json:
schema:
$ref: '#/components/schemas/AdvancedError'
'401':
description: The request could not be completed due to missing authentication.
content:
application/json:
schema:
$ref: '#/components/schemas/AdvancedError'
'403':
description: |-
The request could not be completed. Possible reasons:
* the caller has insufficient permissions.
For deleting all attributes of an existing thing, `WRITE` permission is required.
content:
application/json:
schema:
$ref: '#/components/schemas/AdvancedError'
'404':
description: |-
The request could not be completed. The thing with the given ID or
its attributes were not found.
content:
application/json:
schema:
$ref: '#/components/schemas/AdvancedError'
'412':
$ref: '#/components/responses/PreconditionFailed'
'/things/{thingId}/attributes/{attributePath}':
get:
summary: Retrieve a specific attribute of a specific thing
description: |-
Returns a specific attribute of the thing identified by the `thingId`
path parameter.
The attribute (JSON) can be referenced hierarchically, by
applying JSON Pointer notation (RFC-6901).
Example:
In order to retrieve the `name` field of an `manufacturer` attribute,
the full path would be
`/things/{thingId}/attributes/manufacturer/name`
tags:
- Things
parameters:
- $ref: '#/components/parameters/ThingIdPathParam'
- $ref: '#/components/parameters/AttributesPathPathParam'
- $ref: '#/components/parameters/IfMatchHeaderParamHash'
- $ref: '#/components/parameters/IfNoneMatchHeaderParam'
- $ref: '#/components/parameters/TimeoutParam'
responses:
'200':
description: The attribute was successfully retrieved.
headers:
ETag:
description: |-
The (current server-side) ETag for this (sub-)resource. For top-level resources it is in the format
"rev:[revision]", for sub-resources it has the format "hash:[calculated-hash]".
schema:
type: string
'304':
$ref: '#/components/responses/NotModified'
'400':
description: |-
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.org/ditto/basic-namespaces-and-names.html#namespaced-id)).
content:
application/json:
schema:
$ref: '#/components/schemas/AdvancedError'
'401':
description: The request could not be completed due to missing authentication.
content:
application/json:
schema:
$ref: '#/components/schemas/AdvancedError'
'404':
description: |-
The request could not be completed. The thing with the given ID or
the attribute at the specified path was not found.
content:
application/json:
schema:
$ref: '#/components/schemas/AdvancedError'
'412':
$ref: '#/components/responses/PreconditionFailed'
put:
summary: Create or update a specific attribute of a specific thing
description: |-
Create or update a specific attribute of the thing identified by the
`thingId` path parameter.
* If you specify a new attribute path, this will be created
* If you specify an existing attribute path, this will be updated
The attribute (JSON) can be referenced hierarchically, by applying JSON Pointer notation (RFC-6901).
Example: In order to put the `name` field of an `manufacturer` attribute, the full path would be
`/things/{thingId}/attributes/manufacturer/name`
tags:
- Things
parameters:
- $ref: '#/components/parameters/ThingIdPathParam'
- $ref: '#/components/parameters/AttributesPathPathParam'
- $ref: '#/components/parameters/IfMatchHeaderParamHash'
- $ref: '#/components/parameters/IfNoneMatchHeaderParam'
- $ref: '#/components/parameters/RequestedAcksParam'
- $ref: '#/components/parameters/TimeoutParam'
- $ref: '#/components/parameters/ResponseRequiredParam'
responses:
'201':
description: The attribute was successfully created.
headers:
ETag:
description: |-
The (current server-side) ETag for this (sub-)resource. For top-level resources it is in the format
"rev:[revision]", for sub-resources it has the format "hash:[calculated-hash]".
schema:
type: string
Location:
description: The location of the created attribute resource
schema:
type: string
'204':
description: The attribute was successfully modified.
headers:
ETag:
description: |-
The (current server-side) ETag for this (sub-)resource. For top-level resources it is in the format
"rev:[revision]", for sub-resources it has the format "hash:[calculated-hash]".
schema:
type: string
'400':
description: |-
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.org/ditto/basic-namespaces-and-names.html#namespaced-id)).
content:
application/json:
schema:
$ref: '#/components/schemas/AdvancedError'
'401':
description: The request could not be completed due to missing authentication.
content:
application/json:
schema:
$ref: '#/components/schemas/AdvancedError'
'403':
description: |-
The request could not be completed. Possible reasons:
* the caller has insufficient permissions.
For modifying an attribute of an existing thing, `WRITE` permission is required.
content:
application/json:
schema:
$ref: '#/components/schemas/AdvancedError'
'404':
description: |-
The request could not be completed. The thing with the given ID was
not found.
content:
application/json:
schema:
$ref: '#/components/schemas/AdvancedError'
'412':
$ref: '#/components/responses/PreconditionFailed'
'413':
$ref: '#/components/responses/EntityTooLarge'
requestBody:
content:
application/json:
schema:
type: object
example: {}
description: |-
JSON representation of the value to be created/updated. This may be as
well `null` or an empty object.
Consider that the value has to be a JSON value, examples:
* for a number, the JSON value is the number: `42`
* for a string, the JSON value must be quoted: `"aString"`
* for a boolean, the JSON value is the boolean: `true`
* for an object, the JSON value is the object: `{ "key": "value"}` -} We strongly recommend to use a restricted set of characters for the key (identifier). Currently these identifiers should follow the pattern: [_a-zA-Z][_a-zA-Z0-9\-]*
* for an list, the JSON value is the list: `[ 1,2,3 ]`
required: true
delete:
summary: Delete a specific attribute of a specific thing
description: |-
Deletes a specific attribute of the thing identified by the `thingId`
path parameter.
The attribute (JSON) can be referenced hierarchically, by applying JSON Pointer notation (RFC-6901).
Example: In order to delete the `name` field of an `manufacturer` attribute, the full path would be
`/things/{thingId}/attributes/manufacturer/name`
tags:
- Things
parameters:
- $ref: '#/components/parameters/ThingIdPathParam'
- $ref: '#/components/parameters/AttributesPathPathParam'
- $ref: '#/components/parameters/IfMatchHeaderParamHash'
- $ref: '#/components/parameters/IfNoneMatchHeaderParam'
- $ref: '#/components/parameters/RequestedAcksParam'
- $ref: '#/components/parameters/TimeoutParam'
- $ref: '#/components/parameters/ResponseRequiredParam'
responses:
'204':
description: The attribute was successfully deleted.
'400':
description: |-
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.org/ditto/basic-namespaces-and-names.html#namespaced-id)).
content:
application/json:
schema:
$ref: '#/components/schemas/AdvancedError'
'401':
description: The request could not be completed due to missing authentication.
content:
application/json:
schema:
$ref: '#/components/schemas/AdvancedError'
'403':
description: |-
The request could not be completed. Possible reasons:
* the caller has insufficient permissions.
For deleting a single attribute of an existing thing, `WRITE` permission is required.
content:
application/json:
schema:
$ref: '#/components/schemas/AdvancedError'
'404':
description: |-
The request could not be completed. The thing with the given ID or
the attribute at the specified path was not found.
content:
application/json:
schema:
$ref: '#/components/schemas/AdvancedError'
'412':
$ref: '#/components/responses/PreconditionFailed'
'/things/{thingId}/features':
get:
summary: List all features of a specific thing
description: |-
Returns all features of the thing identified by the `thingId` path
parameter.
tags:
- Features
parameters:
- $ref: '#/components/parameters/ThingIdPathParam'
- $ref: '#/components/parameters/FeaturesFieldsQueryParam'
- $ref: '#/components/parameters/IfMatchHeaderParamHash'
- $ref: '#/components/parameters/IfNoneMatchHeaderParam'
- $ref: '#/components/parameters/TimeoutParam'
responses:
'200':
description: |-
The list of features of the specific thing were successfully
retrieved.
headers:
ETag:
description: |-
The (current server-side) ETag for this (sub-)resource. For top-level resources it is in the format
"rev:[revision]", for sub-resources it has the format "hash:[calculated-hash]".
schema:
type: string
content:
application/json:
schema:
$ref: '#/components/schemas/Features'
example:
featureId1:
definition:
- 'namespace:definition1:v1.0'
properties:
property1: value1
featureId2:
definition:
- 'namespace:definition2:v1.0'
properties:
property2: value2
'304':
$ref: '#/components/responses/NotModified'
'400':
description: |-
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.org/ditto/basic-namespaces-and-names.html#namespaced-id)).
* at least one of the defined query parameters is invalid.
content:
application/json:
schema:
$ref: '#/components/schemas/AdvancedError'
'401':
description: The request could not be completed due to missing authentication.
content:
application/json:
schema:
$ref: '#/components/schemas/AdvancedError'
'404':
description: |-
The request could not be completed. The thing with the given ID was
not found or the features have not been defined.
content:
application/json:
schema:
$ref: '#/components/schemas/AdvancedError'
'412':
$ref: '#/components/responses/PreconditionFailed'
put:
summary: Create or modify all features of a specific thing at once
description: |-
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
}
}
}
}
```
tags:
- Features
parameters:
- $ref: '#/components/parameters/ThingIdPathParam'
- $ref: '#/components/parameters/IfMatchHeaderParamHash'
- $ref: '#/components/parameters/IfNoneMatchHeaderParam'
- $ref: '#/components/parameters/RequestedAcksParam'
- $ref: '#/components/parameters/TimeoutParam'
- $ref: '#/components/parameters/ResponseRequiredParam'
responses:
'201':
description: The features were successfully created.
headers:
ETag:
description: |-
The (current server-side) ETag for this (sub-)resource. For top-level resources it is in the format
"rev:[revision]", for sub-resources it has the format "hash:[calculated-hash]".
schema:
type: string
Location:
description: The location of the created features resource
schema:
type: string
content:
application/json:
schema:
$ref: '#/components/schemas/Features'
example: {}
'204':
description: The features were successfully modified.
headers:
ETag:
description: |-
The (current server-side) ETag for this (sub-)resource. For top-level resources it is in the format
"rev:[revision]", for sub-resources it has the format "hash:[calculated-hash]".
schema:
type: string
'400':
description: |-
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.org/ditto/basic-namespaces-and-names.html#namespaced-id)).
* the JSON body of the feature to be created/modified is invalid
content:
application/json:
schema:
$ref: '#/components/schemas/AdvancedError'
'401':
description: The request could not be completed due to missing authentication.
content:
application/json:
schema:
$ref: '#/components/schemas/AdvancedError'
'403':
description: |-
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:
application/json:
schema:
$ref: '#/components/schemas/AdvancedError'
'404':
description: |-
The request could not be completed. The thing with the given ID was
not found.
content:
application/json:
schema:
$ref: '#/components/schemas/AdvancedError'
'412':
$ref: '#/components/responses/PreconditionFailed'
'413':
$ref: '#/components/responses/EntityTooLarge'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/Features'
example:
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
description: |-
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
required: true
delete:
summary: Delete all features of a specific thing
description: |-
Deletes all features of the thing identified by the `thingId` path
parameter.
tags:
- Features
parameters:
- $ref: '#/components/parameters/ThingIdPathParam'
- $ref: '#/components/parameters/IfMatchHeaderParamHash'
- $ref: '#/components/parameters/IfNoneMatchHeaderParam'
- $ref: '#/components/parameters/RequestedAcksParam'
- $ref: '#/components/parameters/TimeoutParam'
- $ref: '#/components/parameters/ResponseRequiredParam'
responses:
'204':
description: The features were successfully deleted.
'400':
description: |-
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.org/ditto/basic-namespaces-and-names.html#namespaced-id)).
content:
application/json:
schema:
$ref: '#/components/schemas/AdvancedError'
'401':
description: The request could not be completed due to missing authentication.
content:
application/json:
schema:
$ref: '#/components/schemas/AdvancedError'
'403':
description: |-
The request could not be completed. Possible reasons:
* the caller has insufficient permissions.
For deleting all features of an existing thing, `WRITE` permission is required.
content:
application/json:
schema:
$ref: '#/components/schemas/AdvancedError'
'404':
description: |-
The request could not be completed. The thing with the given ID was
not found or the features have not been defined.
content:
application/json:
schema:
$ref: '#/components/schemas/AdvancedError'
'412':
$ref: '#/components/responses/PreconditionFailed'
'/things/{thingId}/features/{featureId}':
get:
summary: Retrieve a specific feature of a specific thing
description: |-
Returns a specific feature identified by the `featureId` path parameter
of the thing identified by the `thingId` path parameter.
tags:
- Features
parameters:
- $ref: '#/components/parameters/ThingIdPathParam'
- $ref: '#/components/parameters/FeatureIdPathPathParam'
- $ref: '#/components/parameters/FeatureFieldsQueryParam'
- $ref: '#/components/parameters/IfMatchHeaderParamHash'
- $ref: '#/components/parameters/IfNoneMatchHeaderParam'
- $ref: '#/components/parameters/TimeoutParam'
responses:
'200':
description: The feature was successfully retrieved.
headers:
ETag:
description: |-
The (current server-side) ETag for this (sub-)resource. For top-level resources it is in the format
"rev:[revision]", for sub-resources it has the format "hash:[calculated-hash]".
schema:
type: string
content:
application/json:
schema:
$ref: '#/components/schemas/Feature'
'304':
$ref: '#/components/responses/NotModified'
'400':
description: |-
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.org/ditto/basic-namespaces-and-names.html#namespaced-id)).
* at least one of the defined query parameters is invalid.
content:
application/json:
schema:
$ref: '#/components/schemas/AdvancedError'
'401':
description: The request could not be completed due to missing authentication.
content:
application/json:
schema:
$ref: '#/components/schemas/AdvancedError'
'404':
description: |-
The request could not be completed. The thing with the given ID or
the feature with the specified `featureId` was not found.
content:
application/json:
schema:
$ref: '#/components/schemas/AdvancedError'
'412':
$ref: '#/components/responses/PreconditionFailed'
put:
summary: Create or modify a specific feature of a specific thing
description: |-
Create or modify a specific feature identified by the `featureId` path
parameter of the thing identified by the `thingId` path parameter.
### Create feature
If the feature ID is new, the feature and all content from the JSON body will be created
### Update feature
If the feature ID is used already in this thing, the feature will be overwrittern
with the content from the JSON body.
Example: Set the `featureId` to **coffee-brewer** and all properties in the body part.
```
{
"definition": ["com.acme:coffeebrewer:0.1.0"],
"properties": {
"brewed-coffees": 42
}
}
```
tags:
- Features
parameters:
- $ref: '#/components/parameters/ThingIdPathParam'
- $ref: '#/components/parameters/FeatureIdPathPathParam'
- $ref: '#/components/parameters/IfMatchHeaderParamHash'
- $ref: '#/components/parameters/IfNoneMatchHeaderParam'
- $ref: '#/components/parameters/RequestedAcksParam'
- $ref: '#/components/parameters/TimeoutParam'
- $ref: '#/components/parameters/ResponseRequiredParam'
responses:
'201':
description: The feature was successfully created.
headers:
ETag:
description: |-
The (current server-side) ETag for this (sub-)resource. For top-level resources it is in the format
"rev:[revision]", for sub-resources it has the format "hash:[calculated-hash]".
schema:
type: string
Location:
description: The location of the created feature resource
schema:
type: string
content:
application/json:
schema:
$ref: '#/components/schemas/Feature'
'204':
description: The feature was successfully modified.
headers:
ETag:
description: |-
The (current server-side) ETag for this (sub-)resource. For top-level resources it is in the format
"rev:[revision]", for sub-resources it has the format "hash:[calculated-hash]".
schema:
type: string
'400':
description: |-
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.org/ditto/basic-namespaces-and-names.html#namespaced-id)).
* the JSON body of the feature to be created/modified is invalid
content:
application/json:
schema:
$ref: '#/components/schemas/AdvancedError'
'401':
description: The request could not be completed due to missing authentication.
content:
application/json:
schema:
$ref: '#/components/schemas/AdvancedError'
'403':
description: |-
The request could not be completed. Possible reasons:
* the caller has insufficient permissions.
For modifying a single feature of an existing thing, `WRITE` permission is required.
content:
application/json:
schema:
$ref: '#/components/schemas/AdvancedError'
'404':
description: |-
The request could not be completed. The thing with the given ID was
not found.
content:
application/json:
schema:
$ref: '#/components/schemas/AdvancedError'
'412':
$ref: '#/components/responses/PreconditionFailed'
'413':
$ref: '#/components/responses/EntityTooLarge'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/Feature'
example:
definition:
- 'com.acme:coffeemaker:0.1.0'
- 'com.acme:coffeemaker:1.1.0'
properties:
connected: true
brewed-coffees: 0
description: |-
JSON representation of the feature to be created/modified.
Consider that the value has to be a JSON object or null.
Examples:
* an empty object: {} - would just create the featureID but would delete all content of the feature
* a nested object with multiple model definitions and multiple properties as shown in the example value field
required: true
delete:
summary: Delete a specific feature of a specific thing
description: |-
Deletes a specific feature identified by the `featureId` path parameter
of the thing identified by the `thingId` path parameter.
tags:
- Features
parameters:
- $ref: '#/components/parameters/ThingIdPathParam'
- $ref: '#/components/parameters/FeatureIdPathPathParam'
- $ref: '#/components/parameters/IfMatchHeaderParamHash'
- $ref: '#/components/parameters/IfNoneMatchHeaderParam'
- $ref: '#/components/parameters/RequestedAcksParam'
- $ref: '#/components/parameters/TimeoutParam'
- $ref: '#/components/parameters/ResponseRequiredParam'
responses:
'204':
description: The feature was successfully deleted.
'400':
description: |-
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.org/ditto/basic-namespaces-and-names.html#namespaced-id)).
content:
application/json:
schema:
$ref: '#/components/schemas/AdvancedError'
'401':
description: The request could not be completed due to missing authentication.
content:
application/json:
schema:
$ref: '#/components/schemas/AdvancedError'
'403':
description: |-
The request could not be completed. Possible reasons:
* the caller has insufficient permissions.
For deleting a single feature of an existing thing, `WRITE` permission is required.
content:
application/json:
schema:
$ref: '#/components/schemas/AdvancedError'
'404':
description: |-
The request could not be completed. The thing with the given ID or
the feature at the specified path was not found.
content:
application/json:
schema:
$ref: '#/components/schemas/AdvancedError'
'412':
$ref: '#/components/responses/PreconditionFailed'
'/things/{thingId}/features/{featureId}/definition':
get:
summary: List the definition of a feature
description: |-
Returns the complete definition field of the feature identified by the `thingId` and
`featureId` path parameter.
tags:
- Features
parameters:
- $ref: '#/components/parameters/ThingIdPathParam'
- $ref: '#/components/parameters/FeatureIdPathPathParam'
- $ref: '#/components/parameters/IfMatchHeaderParamHash'
- $ref: '#/components/parameters/IfNoneMatchHeaderParam'
- $ref: '#/components/parameters/TimeoutParam'
responses:
'200':
description: The definition was successfully retrieved.
headers:
ETag:
description: |-
The (current server-side) ETag for this (sub-)resource. For top-level resources it is in the format
"rev:[revision]", for sub-resources it has the format "hash:[calculated-hash]".
schema:
type: string
content:
application/json:
schema:
$ref: '#/components/schemas/FeatureDefinition'
'304':
$ref: '#/components/responses/NotModified'
'400':
description: |-
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.org/ditto/basic-namespaces-and-names.html#namespaced-id)).
* at least one of the defined query parameters is invalid.
content:
application/json:
schema:
$ref: '#/components/schemas/AdvancedError'
'401':
description: The request could not be completed due to missing authentication.
content:
application/json:
schema:
$ref: '#/components/schemas/AdvancedError'
'404':
description: |-
The request could not be completed. The specified feature has no
definition or the thing with the specified `thingId` or the feature
with `featureId` was not found.
content:
application/json:
schema:
$ref: '#/components/schemas/AdvancedError'
'412':
$ref: '#/components/responses/PreconditionFailed'
put:
summary: Create or update the definition of a feature
description: |-
Create or update the complete definition of a feature identified by the `thingId`
and `featureId` path parameter.
The definition field will be overwritten with the JSON array set in the request body
tags:
- Features
parameters:
- $ref: '#/components/parameters/ThingIdPathParam'
- $ref: '#/components/parameters/FeatureIdPathPathParam'
- $ref: '#/components/parameters/IfMatchHeaderParamHash'
- $ref: '#/components/parameters/IfNoneMatchHeaderParam'
- $ref: '#/components/parameters/RequestedAcksParam'
- $ref: '#/components/parameters/TimeoutParam'
- $ref: '#/components/parameters/ResponseRequiredParam'
responses:
'201':
description: The definition was successfully created.
headers:
ETag:
description: |-
The (current server-side) ETag for this (sub-)resource. For top-level resources it is in the format
"rev:[revision]", for sub-resources it has the format "hash:[calculated-hash]".
schema:
type: string
Location:
description: The location of the created definition resource
schema:
type: string
content:
application/json:
schema:
$ref: '#/components/schemas/FeatureDefinition'
'204':
description: The definition was successfully updated.
headers:
ETag:
description: |-
The (current server-side) ETag for this (sub-)resource. For top-level resources it is in the format
"rev:[revision]", for sub-resources it has the format "hash:[calculated-hash]".
schema:
type: string
'400':
description: |-
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.org/ditto/basic-namespaces-and-names.html#namespaced-id)).
* the JSON body is invalid
content:
application/json:
schema:
$ref: '#/components/schemas/AdvancedError'
'401':
description: The request could not be completed due to missing authentication.
content:
application/json:
schema:
$ref: '#/components/schemas/AdvancedError'
'403':
description: |-
The request could not be completed. Possible reasons:
* the caller has insufficient permissions.
For modifying the definition of an existing feature, `WRITE` permission is required.
content:
application/json:
schema:
$ref: '#/components/schemas/AdvancedError'
'404':
description: |-
The request could not be completed. The thing or the feature with
the given ID was not found.
content:
application/json:
schema:
$ref: '#/components/schemas/AdvancedError'
'412':
$ref: '#/components/responses/PreconditionFailed'
'413':
$ref: '#/components/responses/EntityTooLarge'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/FeatureDefinition'
example:
- 'com.acme:coffeebrewer:0.1.0'
- 'com.acme:coffeebrewer:1.0.0'
description: |-
JSON array of the complete definition to be updated. Consider that the
value has to be a JSON array or `null`.
The content of the JSON array
are strings in the format `"namespace:name:version"` which is
enforced.
required: true
delete:
summary: Delete the definition of a feature
description: |-
Deletes the complete definition of the feature identified by the `thingId` and
`featureId` path parameter.
tags:
- Features
parameters:
- $ref: '#/components/parameters/ThingIdPathParam'
- $ref: '#/components/parameters/FeatureIdPathPathParam'
- $ref: '#/components/parameters/IfMatchHeaderParamHash'
- $ref: '#/components/parameters/IfNoneMatchHeaderParam'
- $ref: '#/components/parameters/RequestedAcksParam'
- $ref: '#/components/parameters/TimeoutParam'
- $ref: '#/components/parameters/ResponseRequiredParam'
responses:
'204':
description: The definition was successfully deleted.
'400':
description: |-
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.org/ditto/basic-namespaces-and-names.html#namespaced-id)).
content:
application/json:
schema:
$ref: '#/components/schemas/AdvancedError'
'401':
description: The request could not be completed due to missing authentication.
content:
application/json:
schema:
$ref: '#/components/schemas/AdvancedError'
'403':
description: |-
The request could not be completed. Possible reasons:
* the caller has insufficient permissions.
For deleting the definition of an existing feature, `WRITE` permission is required.
content:
application/json:
schema:
$ref: '#/components/schemas/AdvancedError'
'404':
description: |-
The request could not be completed. The specified feature has no
definition or the thing with the specified `thingId` or the feature
with `featureId` was not found.
content:
application/json:
schema:
$ref: '#/components/schemas/AdvancedError'
'412':
$ref: '#/components/responses/PreconditionFailed'
'/things/{thingId}/features/{featureId}/properties':
get:
summary: List all properties of a feature
description: |-
Returns all properties of the feature identified by the `thingId` and
`featureId` path parameter.
tags:
- Features
parameters:
- $ref: '#/components/parameters/ThingIdPathParam'
- $ref: '#/components/parameters/FeatureIdPathPathParam'
- $ref: '#/components/parameters/PropertiesFieldsQueryParam'
- $ref: '#/components/parameters/IfMatchHeaderParamHash'
- $ref: '#/components/parameters/IfNoneMatchHeaderParam'
- $ref: '#/components/parameters/TimeoutParam'
responses:
'200':
description: The properties were successfully retrieved.
headers:
ETag:
description: |-
The (current server-side) ETag for this (sub-)resource. For top-level resources it is in the format
"rev:[revision]", for sub-resources it has the format "hash:[calculated-hash]".
schema:
type: string
content:
application/json:
schema:
$ref: '#/components/schemas/FeatureProperties'
'304':
$ref: '#/components/responses/NotModified'
'400':
description: |-
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.org/ditto/basic-namespaces-and-names.html#namespaced-id)).
* at least one of the defined query parameters is invalid.
content:
application/json:
schema:
$ref: '#/components/schemas/AdvancedError'
'401':
description: The request could not be completed due to missing authentication.
content:
application/json:
schema:
$ref: '#/components/schemas/AdvancedError'
'404':
description: |-
The request could not be completed. The specified feature has no
properties or the thing with the specified `thingId` or the feature
with `featureId` was not found.
content:
application/json:
schema:
$ref: '#/components/schemas/AdvancedError'
'412':
$ref: '#/components/responses/PreconditionFailed'
put:
summary: Create or update all properties of a feature at once
description: |-
Create or update the properties of a feature identified by the `thingId`
and `featureId` path parameter.
The properties will be overwritten with the JSON content from the request body.
tags:
- Features
parameters:
- $ref: '#/components/parameters/ThingIdPathParam'
- $ref: '#/components/parameters/FeatureIdPathPathParam'
- $ref: '#/components/parameters/IfMatchHeaderParamHash'
- $ref: '#/components/parameters/IfNoneMatchHeaderParam'
- $ref: '#/components/parameters/RequestedAcksParam'
- $ref: '#/components/parameters/TimeoutParam'
- $ref: '#/components/parameters/ResponseRequiredParam'
responses:
'201':
description: The properties were successfully created.
headers:
ETag:
description: |-
The (current server-side) ETag for this (sub-)resource. For top-level resources it is in the format
"rev:[revision]", for sub-resources it has the format "hash:[calculated-hash]".
schema:
type: string
content:
application/json:
schema:
$ref: '#/components/schemas/FeatureProperties'
'204':
description: The properties were successfully updated.
headers:
ETag:
description: |-
The (current server-side) ETag for this (sub-)resource. For top-level resources it is in the format
"rev:[revision]", for sub-resources it has the format "hash:[calculated-hash]".
schema:
type: string
'400':
description: |-
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.org/ditto/basic-namespaces-and-names.html#namespaced-id)).
* the JSON body of the feature properties to be created/modified is invalid
content:
application/json:
schema:
$ref: '#/components/schemas/AdvancedError'
'401':
description: The request could not be completed due to missing authentication.
content:
application/json:
schema:
$ref: '#/components/schemas/AdvancedError'
'403':
description: |-
The request could not be completed. Possible reasons:
* the caller has insufficient permissions.
For modifying the properties of an existing feature, `WRITE` permission is required.
content:
application/json:
schema:
$ref: '#/components/schemas/AdvancedError'
'404':
description: |-
The request could not be completed. The thing or the feature with
the given ID was not found.
content:
application/json:
schema:
$ref: '#/components/schemas/AdvancedError'
'412':
$ref: '#/components/responses/PreconditionFailed'
'413':
$ref: '#/components/responses/EntityTooLarge'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/FeatureProperties'
example:
configuration:
smartMode: true
brewingTemp: 87
tempToHold: 44
timeoutSeconds: 6000
status:
waterAmount: 731
temperature: 44
description: |-
JSON object of all properties to be updated at once.
Consider that the value has to be a JSON object or `null`. We strongly recommend to use
a restricted set of characters for the key (identifier).
Currently these identifiers should follow the pattern: [_a-zA-Z][_a-zA-Z0-9\-]*
required: true
delete:
summary: Delete all properties of a feature
description: |-
Deletes all properties of the feature identified by the `thingId` and
`featureId` path parameter.
tags:
- Features
parameters:
- $ref: '#/components/parameters/ThingIdPathParam'
- $ref: '#/components/parameters/FeatureIdPathPathParam'
- $ref: '#/components/parameters/IfMatchHeaderParamHash'
- $ref: '#/components/parameters/IfNoneMatchHeaderParam'
- $ref: '#/components/parameters/RequestedAcksParam'
- $ref: '#/components/parameters/TimeoutParam'
- $ref: '#/components/parameters/ResponseRequiredParam'
responses:
'204':
description: The properties were successfully deleted.
'400':
description: |-
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.org/ditto/basic-namespaces-and-names.html#namespaced-id)).
content:
application/json:
schema:
$ref: '#/components/schemas/AdvancedError'
'401':
description: The request could not be completed due to missing authentication.
content:
application/json:
schema:
$ref: '#/components/schemas/AdvancedError'
'403':
description: |-
The request could not be completed. Possible reasons:
* the caller has insufficient permissions.
For deleting the properties of an existing feature, `WRITE` permission is required.
content:
application/json:
schema:
$ref: '#/components/schemas/AdvancedError'
'404':
description: |-
The request could not be completed. The specified feature has no
properties or the thing with the specified `thingId` or the feature
with `featureId` was not found.
content:
application/json:
schema:
$ref: '#/components/schemas/AdvancedError'
'412':
$ref: '#/components/responses/PreconditionFailed'
'/things/{thingId}/features/{featureId}/properties/{propertyPath}':
get:
summary: Retrieve a specific property of a feature
description: |-
Returns the a specific property path of the feature identified by the `thingId` and
`featureId` path parameter.
The property (JSON) can be referenced
hierarchically, by applying JSON Pointer notation (RFC-6901)
### Example
To retrieve the value of the `brewingTemp` in the `water-tank` of our coffeemaker example the full path is:
`/things/{thingId}/features/water-tank/properties/configuration/brewingTemp`
tags:
- Features
parameters:
- $ref: '#/components/parameters/ThingIdPathParam'
- $ref: '#/components/parameters/FeatureIdPathPathParam'
- $ref: '#/components/parameters/PropertyPathPathParam'
- $ref: '#/components/parameters/IfMatchHeaderParamHash'
- $ref: '#/components/parameters/IfNoneMatchHeaderParam'
- $ref: '#/components/parameters/TimeoutParam'
responses:
'200':
description: The property was successfully retrieved.
headers:
ETag:
description: |-
The (current server-side) ETag for this (sub-)resource. For top-level resources it is in the format
"rev:[revision]", for sub-resources it has the format "hash:[calculated-hash]".
schema:
type: string
'304':
$ref: '#/components/responses/NotModified'
'400':
description: |-
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.org/ditto/basic-namespaces-and-names.html#namespaced-id)).
content:
application/json:
schema:
$ref: '#/components/schemas/AdvancedError'
'401':
description: The request could not be completed due to missing authentication.
content:
application/json:
schema:
$ref: '#/components/schemas/AdvancedError'
'404':
description: |-
The request could not be completed. The specified property or the
thing with the specified `thingId` or the feature with `featureId`
was not found.
content:
application/json:
schema:
$ref: '#/components/schemas/AdvancedError'
'412':
$ref: '#/components/responses/PreconditionFailed'
put:
summary: Create or update a specific property of a feature
description: |-
Create or update a specific property of a feature identified by the
`thingId` and `featureId` path parameter.
The property will be created
if it doesn't exist or else updated.
The property (JSON) can be
referenced hierarchically, by applying JSON Pointer notation (RFC-6901),
### Example
To set the value of the brewingTemp in the water-tank of our coffeemaker example the full path is:
`/things/{thingId}/features/water-tank/properties/configuration/brewingTemp`
tags:
- Features
parameters:
- $ref: '#/components/parameters/ThingIdPathParam'
- $ref: '#/components/parameters/FeatureIdPathPathParam'
- $ref: '#/components/parameters/PropertyPathPathParam'
- $ref: '#/components/parameters/IfMatchHeaderParamHash'
- $ref: '#/components/parameters/IfNoneMatchHeaderParam'
- $ref: '#/components/parameters/RequestedAcksParam'
- $ref: '#/components/parameters/TimeoutParam'
- $ref: '#/components/parameters/ResponseRequiredParam'
responses:
'201':
description: The property was successfully created.
headers:
ETag:
description: |-
The (current server-side) ETag for this (sub-)resource. For top-level resources it is in the format
"rev:[revision]", for sub-resources it has the format "hash:[calculated-hash]".
schema:
type: string
'204':
description: The property was successfully updated.
headers:
ETag:
description: |-
The (current server-side) ETag for this (sub-)resource. For top-level resources it is in the format
"rev:[revision]", for sub-resources it has the format "hash:[calculated-hash]".
schema:
type: string
'400':
description: |-
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.org/ditto/basic-namespaces-and-names.html#namespaced-id)).
* the JSON body is invalid
content:
application/json:
schema:
$ref: '#/components/schemas/AdvancedError'
'401':
description: The request could not be completed due to missing authentication.
content:
application/json:
schema:
$ref: '#/components/schemas/AdvancedError'
'403':
description: |-
The request could not be completed. Possible reasons:
* the caller has insufficient permissions.
For creating/updating a property of an existing feature, `WRITE` permission is required.
content:
application/json:
schema:
$ref: '#/components/schemas/AdvancedError'
'404':
description: |-
The request could not be completed. The thing or the feature with
the given ID was not found.
content:
application/json:
schema:
$ref: '#/components/schemas/AdvancedError'
'412':
$ref: '#/components/responses/PreconditionFailed'
'413':
$ref: '#/components/responses/EntityTooLarge'
requestBody:
$ref: '#/paths/~1things~1%7BthingId%7D~1attributes~1%7BattributePath%7D/put/requestBody'
delete:
summary: Delete a specific property of a feature
description: |-
Deletes a specific property of the feature identified by the `thingId`
and `featureId` path parameter.
The property (JSON) can be referenced
hierarchically, by applying JSON Pointer notation (RFC-6901)
### Example
To delete the value of the brewingTemp in the water-tank of our coffeemaker example the full path is:
`/things/{thingId}/features/water-tank/properties/configuration/brewingTemp`
tags:
- Features
parameters:
- $ref: '#/components/parameters/ThingIdPathParam'
- $ref: '#/components/parameters/FeatureIdPathPathParam'
- $ref: '#/components/parameters/PropertyPathPathParam'
- $ref: '#/components/parameters/IfMatchHeaderParamHash'
- $ref: '#/components/parameters/IfNoneMatchHeaderParam'
- $ref: '#/components/parameters/RequestedAcksParam'
- $ref: '#/components/parameters/TimeoutParam'
- $ref: '#/components/parameters/ResponseRequiredParam'
responses:
'204':
description: The property was successfully deleted.
'400':
description: |-
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.org/ditto/basic-namespaces-and-names.html#namespaced-id)).
content:
application/json:
schema:
$ref: '#/components/schemas/AdvancedError'
'401':
description: The request could not be completed due to missing authentication.
content:
application/json:
schema:
$ref: '#/components/schemas/AdvancedError'
'404':
description: |-
The request could not be completed. The specified property or the
thing with the specified `thingId` or the feature with `featureId`
was not found.
content:
application/json:
schema:
$ref: '#/components/schemas/AdvancedError'
'412':
$ref: '#/components/responses/PreconditionFailed'
'/things/{thingId}/features/{featureId}/desiredProperties':
get:
summary: List all desired properties of a feature
description: |-
Returns all desired properties of the feature identified by the `thingId` and
`featureId` path parameter.
tags:
- Features
parameters:
- $ref: '#/components/parameters/ThingIdPathParam'
- $ref: '#/components/parameters/FeatureIdPathPathParam'
- $ref: '#/components/parameters/DesiredPropertiesFieldsQueryParam'
- $ref: '#/components/parameters/IfMatchHeaderParamHash'
- $ref: '#/components/parameters/IfNoneMatchHeaderParam'
- $ref: '#/components/parameters/TimeoutParam'
responses:
'200':
description: The desired properties were successfully retrieved.
headers:
ETag:
description: |-
The (current server-side) ETag for this (sub-)resource. For top-level resources it is in the format
"rev:[revision]", for sub-resources it has the format "hash:[calculated-hash]".
schema:
type: string
content:
application/json:
schema:
$ref: '#/components/schemas/FeatureProperties'
'304':
$ref: '#/components/responses/NotModified'
'400':
description: |-
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.org/ditto/basic-namespaces-and-names.html#namespaced-id)).
* at least one of the defined query parameters is invalid.
content:
application/json:
schema:
$ref: '#/components/schemas/AdvancedError'
'401':
description: The request could not be completed due to missing authentication.
content:
application/json:
schema:
$ref: '#/components/schemas/AdvancedError'
'404':
description: |-
The request could not be completed. The specified feature has no desired
properties or the thing with the specified `thingId` or the feature
with `featureId` was not found.
content:
application/json:
schema:
$ref: '#/components/schemas/AdvancedError'
'412':
$ref: '#/components/responses/PreconditionFailed'
put:
summary: Create or update all desired properties of a feature at once
description: |-
Create or update the desired properties of a feature identified by the `thingId`
and `featureId` path parameter.
The desired properties will be overwritten with the JSON content from the request body.
tags:
- Features
parameters:
- $ref: '#/components/parameters/ThingIdPathParam'
- $ref: '#/components/parameters/FeatureIdPathPathParam'
- $ref: '#/components/parameters/IfMatchHeaderParamHash'
- $ref: '#/components/parameters/IfNoneMatchHeaderParam'
- $ref: '#/components/parameters/RequestedAcksParam'
- $ref: '#/components/parameters/TimeoutParam'
- $ref: '#/components/parameters/ResponseRequiredParam'
responses:
'201':
description: The desired properties were successfully created.
headers:
ETag:
description: |-
The (current server-side) ETag for this (sub-)resource. For top-level resources it is in the format
"rev:[revision]", for sub-resources it has the format "hash:[calculated-hash]".
schema:
type: string
content:
application/json:
schema:
$ref: '#/components/schemas/FeatureProperties'
'204':
description: The desired properties were successfully updated.
headers:
ETag:
description: |-
The (current server-side) ETag for this (sub-)resource. For top-level resources it is in the format
"rev:[revision]", for sub-resources it has the format "hash:[calculated-hash]".
schema:
type: string
'400':
description: |-
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.org/ditto/basic-namespaces-and-names.html#namespaced-id)).
* the JSON body of the desired feature roperties to be created/modified is invalid
content:
application/json:
schema:
$ref: '#/components/schemas/AdvancedError'
'401':
description: The request could not be completed due to missing authentication.
content:
application/json:
schema:
$ref: '#/components/schemas/AdvancedError'
'403':
description: |-
The request could not be completed. Possible reasons:
* the caller has insufficient permissions.
For modifying the desired properties of an existing feature, `WRITE` permission is required.
content:
application/json:
schema:
$ref: '#/components/schemas/AdvancedError'
'404':
description: |-
The request could not be completed. The thing or the feature with
the given ID was not found.
content:
application/json:
schema:
$ref: '#/components/schemas/AdvancedError'
'412':
$ref: '#/components/responses/PreconditionFailed'
'413':
$ref: '#/components/responses/EntityTooLarge'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/FeatureProperties'
example:
configuration:
smartMode: true
brewingTemp: 87
tempToHold: 44
timeoutSeconds: 6000
status:
waterAmount: 731
temperature: 44
description: |-
JSON object of all desried properties to be updated at once.
Consider that the value has to be a JSON object or `null`. We strongly recommend to use
a restricted set of characters for the key (identifier).
Currently these identifiers should follow the pattern: [_a-zA-Z][_a-zA-Z0-9\-]*
required: true
delete:
summary: Delete all desired properties of a feature
description: |-
Deletes all desired properties of the feature identified by the `thingId` and
`featureId` path parameter.
tags:
- Features
parameters:
- $ref: '#/components/parameters/ThingIdPathParam'
- $ref: '#/components/parameters/FeatureIdPathPathParam'
- $ref: '#/components/parameters/IfMatchHeaderParamHash'
- $ref: '#/components/parameters/IfNoneMatchHeaderParam'
- $ref: '#/components/parameters/RequestedAcksParam'
- $ref: '#/components/parameters/TimeoutParam'
- $ref: '#/components/parameters/ResponseRequiredParam'
responses:
'204':
description: The desired properties were successfully deleted.
'400':
description: |-
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.org/ditto/basic-namespaces-and-names.html#namespaced-id)).
content:
application/json:
schema:
$ref: '#/components/schemas/AdvancedError'
'401':
description: The request could not be completed due to missing authentication.
content:
application/json:
schema:
$ref: '#/components/schemas/AdvancedError'
'403':
description: |-
The request could not be completed. Possible reasons:
* the caller has insufficient permissions.
For deleting the desired properties of an existing feature, `WRITE` permission is required.
content:
application/json:
schema:
$ref: '#/components/schemas/AdvancedError'
'404':
description: |-
The request could not be completed. The specified feature has no desired
properties or the thing with the specified `thingId` or the feature
with `featureId` was not found.
content:
application/json:
schema:
$ref: '#/components/schemas/AdvancedError'
'412':
$ref: '#/components/responses/PreconditionFailed'
'/things/{thingId}/features/{featureId}/desiredProperties/{propertyPath}':
get:
summary: Retrieve a specific desired property of a feature
description: |-
Returns the a specific desired property path of the feature identified by the `thingId` and
`featureId` path parameter.
The desired property (JSON) can be referenced
hierarchically, by applying JSON Pointer notation (RFC-6901)
### Example
To retrieve the value of the `brewingTemp` in the `water-tank` of our coffeemaker example the full path is:
`/things/{thingId}/features/water-tank/desiredProperties/configuration/brewingTemp`
tags:
- Features
parameters:
- $ref: '#/components/parameters/ThingIdPathParam'
- $ref: '#/components/parameters/FeatureIdPathPathParam'
- $ref: '#/components/parameters/PropertyPathPathParam'
- $ref: '#/components/parameters/IfMatchHeaderParamHash'
- $ref: '#/components/parameters/IfNoneMatchHeaderParam'
- $ref: '#/components/parameters/TimeoutParam'
responses:
'200':
description: The desired property was successfully retrieved.
headers:
ETag:
description: |-
The (current server-side) ETag for this (sub-)resource. For top-level resources it is in the format
"rev:[revision]", for sub-resources it has the format "hash:[calculated-hash]".
schema:
type: string
'304':
$ref: '#/components/responses/NotModified'
'400':
description: |-
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.org/ditto/basic-namespaces-and-names.html#namespaced-id)).
content:
application/json:
schema:
$ref: '#/components/schemas/AdvancedError'
'401':
description: The request could not be completed due to missing authentication.
content:
application/json:
schema:
$ref: '#/components/schemas/AdvancedError'
'404':
description: |-
The request could not be completed. The specified desired property or the
thing with the specified `thingId` or the feature with `featureId`
was not found.
content:
application/json:
schema:
$ref: '#/components/schemas/AdvancedError'
'412':
$ref: '#/components/responses/PreconditionFailed'
put:
summary: Create or update a specific desired property of a feature
description: |-
Create or update a specific desired property of a feature identified by the
`thingId` and `featureId` path parameter.
The desired property will be created
if it doesn't exist or else updated.
The desired property (JSON) can be
referenced hierarchically, by applying JSON Pointer notation (RFC-6901),
### Example
To set the value of the brewingTemp in the water-tank of our coffeemaker example the full path is:
`/things/{thingId}/features/water-tank/desiredProperties/configuration/brewingTemp`
tags:
- Features
parameters:
- $ref: '#/components/parameters/ThingIdPathParam'
- $ref: '#/components/parameters/FeatureIdPathPathParam'
- $ref: '#/components/parameters/PropertyPathPathParam'
- $ref: '#/components/parameters/IfMatchHeaderParamHash'
- $ref: '#/components/parameters/IfNoneMatchHeaderParam'
- $ref: '#/components/parameters/RequestedAcksParam'
- $ref: '#/components/parameters/TimeoutParam'
- $ref: '#/components/parameters/ResponseRequiredParam'
responses:
'201':
description: The desired property was successfully created.
headers:
ETag:
description: |-
The (current server-side) ETag for this (sub-)resource. For top-level resources it is in the format
"rev:[revision]", for sub-resources it has the format "hash:[calculated-hash]".
schema:
type: string
'204':
description: The desired property was successfully updated.
headers:
ETag:
description: |-
The (current server-side) ETag for this (sub-)resource. For top-level resources it is in the format
"rev:[revision]", for sub-resources it has the format "hash:[calculated-hash]".
schema:
type: string
'400':
description: |-
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.org/ditto/basic-namespaces-and-names.html#namespaced-id)).
* the JSON body is invalid
content:
application/json:
schema:
$ref: '#/components/schemas/AdvancedError'
'401':
description: The request could not be completed due to missing authentication.
content:
application/json:
schema:
$ref: '#/components/schemas/AdvancedError'
'403':
description: |-
The request could not be completed. Possible reasons:
* the caller has insufficient permissions.
For creating/updating a desired property of an existing feature, `WRITE` permission is required.
content:
application/json:
schema:
$ref: '#/components/schemas/AdvancedError'
'404':
description: |-
The request could not be completed. The thing or the feature with
the given ID was not found.
content:
application/json:
schema:
$ref: '#/components/schemas/AdvancedError'
'412':
$ref: '#/components/responses/PreconditionFailed'
'413':
$ref: '#/components/responses/EntityTooLarge'
requestBody:
$ref: '#/paths/~1things~1%7BthingId%7D~1attributes~1%7BattributePath%7D/put/requestBody'
delete:
summary: Delete a specific desired property of a feature
description: |-
Deletes a specific desired property of the feature identified by the `thingId`
and `featureId` path parameter.
The desired property (JSON) can be referenced
hierarchically, by applying JSON Pointer notation (RFC-6901)
### Example
To delete the value of the brewingTemp in the water-tank of our coffeemaker example the full path is:
`/things/{thingId}/features/water-tank/desiredProperties/configuration/brewingTemp`
tags:
- Features
parameters:
- $ref: '#/components/parameters/ThingIdPathParam'
- $ref: '#/components/parameters/FeatureIdPathPathParam'
- $ref: '#/components/parameters/PropertyPathPathParam'
- $ref: '#/components/parameters/IfMatchHeaderParamHash'
- $ref: '#/components/parameters/IfNoneMatchHeaderParam'
- $ref: '#/components/parameters/RequestedAcksParam'
- $ref: '#/components/parameters/TimeoutParam'
- $ref: '#/components/parameters/ResponseRequiredParam'
responses:
'204':
description: The desired property was successfully deleted.
'400':
description: |-
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.org/ditto/basic-namespaces-and-names.html#namespaced-id)).
content:
application/json:
schema:
$ref: '#/components/schemas/AdvancedError'
'401':
description: The request could not be completed due to missing authentication.
content:
application/json:
schema:
$ref: '#/components/schemas/AdvancedError'
'404':
description: |-
The request could not be completed. The specified desired property or the
thing with the specified `thingId` or the feature with `featureId`
was not found.
content:
application/json:
schema:
$ref: '#/components/schemas/AdvancedError'
'412':
$ref: '#/components/responses/PreconditionFailed'
'/things/{thingId}/inbox/claim':
post:
summary: Initiates claiming a specific thing in order to gain access
description: |-
### Why
A claiming process may enable an end-user to claim things and proof ownership thereof.
Such a process is initially triggered via a claim message.
This message can be sent to the things service with the HTTP API or the things-client.
### How
At this resource you can send a "claim" message to the thing identified
by the `thingId` path parameter in order to gain access to it. The "claim" message is forwarded
together with the request body and `Content-Type` header to client(s)
which registered for Claim messages of the specific thing.
The decision whether to grant access (by setting permissions) is
completely up to the client(s) which handle the "claim" message.
The HTTP request blocks until all acknowledgement requests are fulfilled.
By default, it blocks until a response to the issued "claim" message is
available or until the `timeout` is expired. If many clients respond to
the issued message, the first response will complete the HTTP request.
Note that the client chooses which HTTP status code it wants to return. Ditto
will forward the status code to you. (Also note that '204 - No Content' status code
will never return a body, even if the client responded with a body).
### Who
No special permission is required to issue a claim message.
### Example
See [Claiming](https://www.eclipse.org/ditto/protocol-specification-things-messages.html#sending-and-handling-claim-messages) concept in detail and example in GitHub.
However, in that scenario, the policy should grant you READ and WRITE permission on
the "message:/" resource in order to be able to send the message and read the response.
Further, the things-client which handles the "claim" message, needs permission to change the policy itself
(i.e. READ and WRITE permission on the "policy:/" resource).
tags:
- Messages
parameters:
- $ref: '#/components/parameters/ThingIdPathParam'
- $ref: '#/components/parameters/MessageClaimTimeoutParam'
- $ref: '#/components/parameters/LiveMessageRequestedAcksParam'
responses:
'200':
description: |-
The Claim message was processed successfully and the response body
contains the custom response. The response body may contain
arbitrary data chosen by the recipient. The response code defaults
to `200` but may be chosen by the recipient too.
'204':
description: |-
The Claim message was processed successfully and no custom response
body was set. The response code defaults to `204` but may be chosen
by the recipient.
'400':
description: |-
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.org/ditto/basic-namespaces-and-names.html#namespaced-id)).
* at least one of the defined path parameters is invalid
content:
application/json:
schema:
$ref: '#/components/schemas/AdvancedError'
'401':
description: The request could not be completed due to missing authentication.
content:
application/json:
schema:
$ref: '#/components/schemas/AdvancedError'
'404':
description: |-
The request could not be completed. Possible reasons:
* the referenced thing does not exist.
content:
application/json:
schema:
$ref: '#/components/schemas/AdvancedError'
'408':
description: The request could not be completed due to timeout.
content:
application/json:
schema:
$ref: '#/components/schemas/AdvancedError'
'413':
$ref: '#/components/responses/MessageTooLarge'
'429':
description: |-
The user has sent too many requests in a given amount of time ("rate
limiting").
content:
application/json:
schema:
$ref: '#/components/schemas/AdvancedError'
'503':
$ref: '#/components/responses/MessageTimeout'
requestBody:
content:
application/json:
schema:
type: string
example: ''
application/octet-stream:
schema:
type: string
example: ''
text/plain:
schema:
type: string
example: ''
description: |-
Payload of the message with max size of 250 kB. It can be any HTTP
supported content, including binary content.
'/things/{thingId}/inbox/messages/{messageSubject}':
post:
summary: Send a message TO a specific thing
description: |-
### Why
A message can be sent to a thing or one of its features in order to invoke an operation on the device.
### How
Send a message with a `messageSubject` **to** the thing
identified by the `thingId` path parameter. The request body contains
the message payload and the `Content-Type` header defines its type.
The HTTP request blocks until all acknowledgement requests are fulfilled.
By default, it blocks until a response to the message is available
or until the `timeout` is expired. If many clients respond to
the issued message, the first response will complete the HTTP request.
In order to handle the message in a fire and forget manner, add
a query-parameter `timeout=0` to the request.
Note that the client chooses which HTTP status code it wants to return. Ditto
will forward the status code to you. (Also note that '204 - No Content' status code
will never return a body, even if the client responded with a body).
### Who
You will need `WRITE` permission on the root "message:/" resource, or at least
the resource `message:/inbox/messages/messageSubject`. The receiving device needs `READ` permission on the resource.
Such permission is managed within the policy which controls the access on the thing.
### Example
Given you have a "coffemaker" thing as shown in the examples for the `things` resources.
The `messageSubject` understood by such a device would be "makeCoffee".
Further, as in our example the "brewed-coffees" counter would increase as a response, you would need `WRITE`
permission for the things resource, at least at the respective path
`/things/{thingId}/features/coffee-brewer/properties/brewed-coffees`
tags:
- Messages
parameters:
- $ref: '#/components/parameters/ThingIdPathParam'
- $ref: '#/components/parameters/MessageSubjectPathParam'
- $ref: '#/components/parameters/MessageTimeoutParam'
- $ref: '#/components/parameters/LiveMessageRequestedAcksParam'
responses:
'202':
description: The message was sent but not necessarily received by the thing (fire and forget).
'400':
description: |-
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.org/ditto/basic-namespaces-and-names.html#namespaced-id)).
* at least one of the defined path parameters is invalid
content:
application/json:
schema:
$ref: '#/components/schemas/AdvancedError'
'401':
description: The request could not be completed due to missing authentication.
content:
application/json:
schema:
$ref: '#/components/schemas/AdvancedError'
'403':
description: |-
The request could not be completed. Possible reasons:
* the caller has insufficient permissions.
You need `WRITE` permission on the resource `message:/inbox/messages/{messageSubject}`.
content:
application/json:
schema:
$ref: '#/components/schemas/AdvancedError'
'404':
description: |-
The request could not be completed. Possible reasons:
* the referenced thing does not exist.
* the caller has insufficient permissions to interact with the messages of referenced thing.
content:
application/json:
schema:
$ref: '#/components/schemas/AdvancedError'
'408':
description: The request could not be completed due to timeout.
content:
application/json:
schema:
$ref: '#/components/schemas/AdvancedError'
'413':
$ref: '#/components/responses/MessageTooLarge'
'503':
$ref: '#/components/responses/MessageTimeout'
requestBody:
$ref: '#/paths/~1things~1%7BthingId%7D~1inbox~1claim/post/requestBody'
'/things/{thingId}/outbox/messages/{messageSubject}':
post:
summary: Send a message FROM a specific thing
description: |-
Send a message with the subject `messageSubject` **from** the thing
identified by the `thingId` path parameter. The request body contains
the message payload and the `Content-Type` header defines its type.
The HTTP request blocks until all acknowledgement requests are fulfilled.
By default, it blocks until a response to the message is available
or until the `timeout` is expired. If many clients respond to
the issued message, the first response will complete the HTTP request.
In order to handle the message in a fire and forget manner, add
a query-parameter `timeout=0` to the request.
Note that the client chooses which HTTP status code it wants to return. Ditto
will forward the status code to you. (Also note that '204 - No Content' status code
will never return a body, even if the client responded with a body).
### Who
You will need `WRITE` permission on the root "message:/" resource, or at least
the resource `message:/outbox/messages/messageSubject`.
Such permission is managed within the policy which controls the access on the thing.
tags:
- Messages
parameters:
- $ref: '#/components/parameters/ThingIdPathParam'
- $ref: '#/components/parameters/MessageSubjectPathParam'
- $ref: '#/components/parameters/MessageTimeoutParam'
- $ref: '#/components/parameters/LiveMessageRequestedAcksParam'
responses:
'202':
description: The message was sent (fire and forget).
'400':
description: |-
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.org/ditto/basic-namespaces-and-names.html#namespaced-id)).
* at least one of the defined path parameters is invalid.
content:
application/json:
schema:
$ref: '#/components/schemas/AdvancedError'
'401':
description: The request could not be completed due to missing authentication.
content:
application/json:
schema:
$ref: '#/components/schemas/AdvancedError'
'403':
description: |-
The request could not be completed. Possible reasons:
* the caller has insufficient permissions.
You need `WRITE` permission on the resource `message:/outbox/messages/{messageSubject}`.
content:
application/json:
schema:
$ref: '#/components/schemas/AdvancedError'
'404':
description: |-
The request could not be completed. Possible reasons:
* the referenced thing does not exist.
* the caller has insufficient permissions to interact with the messages of referenced thing.
content:
application/json:
schema:
$ref: '#/components/schemas/AdvancedError'
'408':
description: The request could not be completed due to timeout.
content:
application/json:
schema:
$ref: '#/components/schemas/AdvancedError'
'413':
$ref: '#/components/responses/MessageTooLarge'
'503':
$ref: '#/components/responses/MessageTimeout'
requestBody:
$ref: '#/paths/~1things~1%7BthingId%7D~1inbox~1claim/post/requestBody'
'/things/{thingId}/features/{featureId}/inbox/messages/{messageSubject}':
post:
summary: Send a message TO a specific feature of a specific thing
description: |-
Send a message with the subject `messageSubject` **to** the feature
specified by the `featureId` and `thingId` path parameter. The request
body contains the message payload and the `Content-Type` header defines
its type.
The HTTP request blocks until all acknowledgement requests are fulfilled.
By default, it blocks until a response to the message is available
or until the `timeout` is expired. If many clients respond to
the issued message, the first response will complete the HTTP request.
In order to handle the message in a fire and forget manner, add
a query-parameter `timeout=0` to the request.
Note that the client chooses which HTTP status code it wants to return. Ditto
will forward the status code to you. (Also note that '204 - No Content' status code
will never return a body, even if the client responded with a body).
### Who
You will need `WRITE` permission on the root "message:/" resource, or at least
the resource `message:/features/featureId/inbox/messages/messageSubject`. The receiving device needs `READ` permission on the resource.
Such permission is managed within the policy which controls the access on the thing.
tags:
- Messages
parameters:
- $ref: '#/components/parameters/ThingIdPathParam'
- $ref: '#/components/parameters/FeatureIdPathPathParam'
- $ref: '#/components/parameters/MessageSubjectPathParam'
- $ref: '#/components/parameters/MessageTimeoutParam'
- $ref: '#/components/parameters/LiveMessageRequestedAcksParam'
responses:
'202':
description: |-
The message was sent but not necessarily received by the feature
(fire and forget).
'400':
description: |-
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.org/ditto/basic-namespaces-and-names.html#namespaced-id)).
* at least one of the defined path parameters is invalid.
content:
application/json:
schema:
$ref: '#/components/schemas/AdvancedError'
'401':
description: The request could not be completed due to missing authentication.
content:
application/json:
schema:
$ref: '#/components/schemas/AdvancedError'
'403':
description: |-
The request could not be completed. Possible reasons:
* the caller has insufficient permissions.
You need `WRITE` permission on the resource `message:/features/{featureId}/inbox/messages/{messageSubject}`.
content:
application/json:
schema:
$ref: '#/components/schemas/AdvancedError'
'404':
description: |-
The request could not be completed. Possible reasons:
* the referenced thing does not exist.
* the caller has insufficient permissions to interact with the messages of referenced thing.
content:
application/json:
schema:
$ref: '#/components/schemas/AdvancedError'
'408':
description: The request could not be completed due to timeout.
content:
application/json:
schema:
$ref: '#/components/schemas/AdvancedError'
'413':
$ref: '#/components/responses/MessageTooLarge'
'503':
$ref: '#/components/responses/MessageTimeout'
requestBody:
$ref: '#/paths/~1things~1%7BthingId%7D~1inbox~1claim/post/requestBody'
'/things/{thingId}/features/{featureId}/outbox/messages/{messageSubject}':
post:
summary: Send a message FROM a specific feature of a specific thing
description: |-
Send a message with the subject `messageSubject` **from** the feature
specified by the `featureId` and `thingId` path parameter. The request
body contains the message payload and the `Content-Type` header defines
its type.
The HTTP request blocks until all acknowledgement requests are fulfilled.
By default, it blocks until a response to the message is available
or until the `timeout` is expired. If many clients respond to
the issued message, the first response will complete the HTTP request.
In order to handle the message in a fire and forget manner, add
a query-parameter `timeout=0` to the request.
Note that the client chooses which HTTP status code it wants to return. Ditto
will forward the status code to you. (Also note that '204 - No Content' status code
will never return a body, even if the client responded with a body).
### Who
You will need `WRITE` permission on the root "message:/" resource, or at least
the resource `message:/features/featureId/outbox/messages/messageSubject`.
Such permission is managed within the policy which controls the access on the thing.
tags:
- Messages
parameters:
- $ref: '#/components/parameters/ThingIdPathParam'
- $ref: '#/components/parameters/FeatureIdPathPathParam'
- $ref: '#/components/parameters/MessageSubjectPathParam'
- $ref: '#/components/parameters/MessageTimeoutParam'
- $ref: '#/components/parameters/LiveMessageRequestedAcksParam'
responses:
'202':
description: The message was sent (fire and forget).
'400':
description: |-
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.org/ditto/basic-namespaces-and-names.html#namespaced-id)).
* at least one of the defined path parameters is valid.
content:
application/json:
schema:
$ref: '#/components/schemas/AdvancedError'
'401':
description: The request could not be completed due to missing authentication.
content:
application/json:
schema:
$ref: '#/components/schemas/AdvancedError'
'403':
description: |-
The request could not be completed. Possible reasons:
* the caller has insufficient permissions.
You need `WRITE` permission on the resource `message:/features/{featureId}/outbox/messages/{messageSubject}`.
content:
application/json:
schema:
$ref: '#/components/schemas/AdvancedError'
'404':
description: |-
The request could not be completed. Possible reasons:
* the referenced thing does not exist.
* the caller has insufficient permissions to interact with the messages of referenced thing.
content:
application/json:
schema:
$ref: '#/components/schemas/AdvancedError'
'408':
description: The request could not be completed due to timeout.
content:
application/json:
schema:
$ref: '#/components/schemas/AdvancedError'
'413':
$ref: '#/components/responses/MessageTooLarge'
'503':
$ref: '#/components/responses/MessageTimeout'
requestBody:
$ref: '#/paths/~1things~1%7BthingId%7D~1inbox~1claim/post/requestBody'
'/policies/{policyId}':
get:
summary: Retrieve a specific policy
description: |-
Returns the complete policy identified by the `policyId` path parameter. The
response contains the policy as JSON object.
Tip: If you don't know the policy ID, request it via GET ​/things​/{thingId}.
tags:
- Policies
parameters:
- $ref: '#/components/parameters/PolicyIdPathParam'
- $ref: '#/components/parameters/IfMatchHeaderParam'
- $ref: '#/components/parameters/IfNoneMatchHeaderParam'
- $ref: '#/components/parameters/TimeoutParam'
responses:
'200':
description: |-
The request successfully returned completed and returned is the
policy.
headers:
ETag:
description: |-
The (current server-side) ETag for this (sub-)resource. For top-level resources it is in the format
"rev:[revision]", for sub-resources it has the format "hash:[calculated-hash]".
schema:
type: string
content:
application/json:
schema:
$ref: '#/components/schemas/Policy'
'304':
$ref: '#/components/responses/NotModified'
'400':
description: |-
The request could not be completed. Possible reasons:
* the `policyId` does not conform to the namespaced entity ID notation (see [Ditto documentation on namespaced entity IDs](https://www.eclipse.org/ditto/basic-namespaces-and-names.html#namespaced-id))
content:
application/json:
schema:
$ref: '#/components/schemas/AdvancedError'
'401':
description: The request could not be completed due to missing authentication.
content:
application/json:
schema:
$ref: '#/components/schemas/AdvancedError'
'404':
description: |-
The request could not be completed. The policy with the given ID was
not found in the context of the authenticated user.
content:
application/json:
schema:
$ref: '#/components/schemas/AdvancedError'
'412':
$ref: '#/components/responses/PreconditionFailed'
put:
summary: Create or update a policy with a specified ID
description: |-
Create or update the policy specified by the policyId path parameter.
* If you set a new policyId in the path, a new policy will be created.
* If you set an existing policyId in the path, the policy will be updated.
### Create a new policy
At the initial creation of a policy, at least one valid entry is required. However, you can create a full-fledged policy all at once.
By default the authorized subject needs WRITE permission on the root resource of the created policy. You can
however omit this check by setting the parameter `allow-policy-lockout` to `true`.
Example: To create a policy for multiple coffee maker things,
which gives **yourself** all permissions on all resources, set the policyId in the path,
e.g. to "com.acme.coffeemaker:policy-01" and the body part, like in the following snippet.
```
{
"entries": {
"DEFAULT": {
"subjects": {
"{{ request:subjectId }}": {
"type": "the creator"
}
},
"resources": {
"policy:/": {
"grant": [
"READ",
"WRITE"
],
"revoke": []
},
"thing:/": {
"grant": [
"READ",
"WRITE"
],
"revoke": []
},
"message:/": {
"grant": [
"READ",
"WRITE"
],
"revoke": []
}
}
}
}
}
```
### Update an existing policy
For updating an existing policy, the authorized subject needs WRITE permission on the policy's root resource.
The ID of a policy cannot be changed after creation. Any `policyId` specified in the request body is therefore ignored.
### Partially update an existing policy
Partial updates are not supported.
If you need to create or update a specific label, resource, or subject, please use the respective sub-resources.
tags:
- Policies
parameters:
- $ref: '#/components/parameters/PolicyIdPathParam'
- $ref: '#/components/parameters/IfMatchHeaderParam'
- $ref: '#/components/parameters/IfNoneMatchHeaderParam'
- $ref: '#/components/parameters/TimeoutParam'
- $ref: '#/components/parameters/ResponseRequiredParam'
- $ref: '#/components/parameters/AllowPolicyLockoutParam'
responses:
'201':
description: The policy was successfully created.
headers:
ETag:
description: |-
The (current server-side) ETag for this (sub-)resource. For top-level resources it is in the format
"rev:[revision]", for sub-resources it has the format "hash:[calculated-hash]".
schema:
type: string
Location:
description: The location of the created policy resource
schema:
type: string
content:
application/json:
schema:
$ref: '#/components/schemas/Policy'
'204':
description: The policy was successfully updated.
headers:
ETag:
description: |-
The (current server-side) ETag for this (sub-)resource. For top-level resources it is in the format
"rev:[revision]", for sub-resources it has the format "hash:[calculated-hash]".
schema:
type: string
'400':
description: |-
The request could not be completed. Possible reasons:
* the `policyId` does not conform to the namespaced entity ID notation (see [Ditto documentation on namespaced entity IDs](https://www.eclipse.org/ditto/basic-namespaces-and-names.html#namespaced-id))
* the JSON body of the policy to be created/modified is invalid
content:
application/json:
schema:
$ref: '#/components/schemas/AdvancedError'
'401':
description: The request could not be completed due to missing authentication.
content:
application/json:
schema:
$ref: '#/components/schemas/AdvancedError'
'403':
description: |-
The request could not be completed. Possible reasons:
* the caller has insufficient permissions.
You need `WRITE` permission on the root `policy:/` resource,
without any revoke in a deeper path of the policy resource.
(You can omit this check by setting the `allow-policy-lockout` parameter.)
content:
application/json:
schema:
$ref: '#/components/schemas/AdvancedError'
'404':
description: |-
The request could not be completed. The policy with the given ID was
not found in the context of the authenticated user.
content:
application/json:
schema:
$ref: '#/components/schemas/AdvancedError'
'412':
$ref: '#/components/responses/PreconditionFailed'
'413':
$ref: '#/components/responses/EntityTooLarge'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/Policy'
example:
entries:
DEFAULT:
subjects:
'{{ request:subjectId }}':
type: the creator
resources:
'policy:/':
grant:
- READ
- WRITE
revoke: []
'thing:/':
grant:
- READ
- WRITE
revoke: []
'message:/':
grant:
- READ
- WRITE
revoke: []
description: |-
JSON representation of the policy.
Use the placeholder `{{ request:subjectId }}` in order to let the
backend insert the authenticated subjectId of the HTTP request.
required: true
delete:
summary: Delete a specific policy
description: |-
Deletes the policy identified by the `policyId` path parameter. Deleting
a policy does not implicitly delete other entities (e.g. things) which
use this policy.
Note: Delete the respective things **before** deleting the
policy, otherwise nobody has permission to read, update, or delete the things.
If you accidentally run into such a scenario, re-create the policy via
PUT `/policies/{policyId}`.
tags:
- Policies
parameters:
- $ref: '#/components/parameters/PolicyIdPathParam'
- $ref: '#/components/parameters/IfMatchHeaderParam'
- $ref: '#/components/parameters/IfNoneMatchHeaderParam'
- $ref: '#/components/parameters/TimeoutParam'
- $ref: '#/components/parameters/ResponseRequiredParam'
responses:
'204':
description: The policy was successfully deleted.
'400':
description: |-
The request could not be completed. Possible reasons:
* the `policyId` does not conform to the namespaced entity ID notation (see [Ditto documentation on namespaced entity IDs](https://www.eclipse.org/ditto/basic-namespaces-and-names.html#namespaced-id))
content:
application/json:
schema:
$ref: '#/components/schemas/AdvancedError'
'401':
description: The request could not be completed due to missing authentication.
content:
application/json:
schema:
$ref: '#/components/schemas/AdvancedError'
'403':
description: |-
The request could not be completed. Possible reasons:
* the caller has insufficient permissions.
You need `WRITE` permission on the root `policy:/` resource,
without any revoke in a deeper path of the policy resource.having any revoke.
content:
application/json:
schema:
$ref: '#/components/schemas/AdvancedError'
'404':
description: |-
The request could not be completed. The policy with the given ID was
not found in the context of the authenticated user.
content:
application/json:
schema:
$ref: '#/components/schemas/AdvancedError'
'412':
$ref: '#/components/responses/PreconditionFailed'
'/policies/{policyId}/entries':