blob: 50cae9ae7886618452c8d189e84d0faef0150b1d [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
- name: CloudEvents
description: Process CloudEvents in Ditto
security:
- Google:
- openid
- NginxBasic: []
- Bearer: []
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:
$ref: '#/components/requestBodies/Definition'
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:
$ref: '#/components/requestBodies/Attributes'
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:
$ref: '#/components/requestBodies/Value'
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: '#/components/requestBodies/Value'
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: '#/components/requestBodies/Value'
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:
$ref: '#/components/requestBodies/Payload'
'/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: '#/components/requestBodies/Payload'
'/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: '#/components/requestBodies/Payload'
'/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: '#/components/requestBodies/Payload'
'/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: '#/components/requestBodies/Payload'
'/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 of a thing, 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/NewPolicy'
'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/NewPolicy'
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}/actions/activateTokenIntegration':
post:
summary: Activate subjects for this policy derived from the token
description: |-
**This action only works when authenticated with a Json Web Token (JWT).**
Based on the authenticated token (JWT), **for each policy entry** matching those conditions:
* the authenticated token is granted the `EXECUTE` permission to perform the `activateTokenIntegration` action
* one of the subject IDs is contained in the authenticated token
* at least one `READ` permission to a `thing:/` resource path is granted
a new subject is **injected into the matched policy entry** calculated with information extracted from the
authenticated JWT.
The injected subjects expire when the JWT expires.
tags:
- Policies
parameters:
- $ref: '#/components/parameters/PolicyIdPathParam'
responses:
'204':
description: The request was successful. Subjects were injected into authorized policy entries.
'400':
description: The request could not be completed because the authentication was not performed with a JWT.
'403':
description: |-
The request could not be completed because the authenticated JWT did not have the `EXECUTE` permission on any
entries of the policy.
'404':
description: |-
The request could not be completed because no policy entry matched the following conditions:
* containing a a subject ID matching the JWT's authenticated subject
* containing a `READ` permission granted to a `thing:/` resource path
requestBody:
$ref: '#/components/requestBodies/ActivateTokenIntegration'
'/policies/{policyId}/actions/deactivateTokenIntegration':
post:
summary: Deactivate subjects for this policy derived from the token
description: |-
**This action only works when authenticated with a Json Web Token (JWT).**
Based on the authenticated token (JWT), **for each policy entry** matching those conditions:
* the authenticated token is granted the `EXECUTE` permission to perform the `deactivateTokenIntegration` action
* one of the subject IDs is contained in the authenticated token
the calculated subject with information extracted from the authenticated JWT is **removed
from the matched policy entry**.
tags:
- Policies
parameters:
- $ref: '#/components/parameters/PolicyIdPathParam'
responses:
'204':
description: The request was successful. Subjects were removed from authorized policy entries.
'400':
description: The request could not be completed because the authentication was not performed with a JWT.
'403':
description: |-
The request could not be completed because the authenticated JWT did not have the `EXECUTE` permission on any
entries of the policy.
'404':
description: |-
The request could not be completed because no policy entry matched the following conditions:
* containing a a subject ID matching the JWT's authenticated subject
'/policies/{policyId}/entries':
get:
summary: Retrieve the entries of a specific policy
description: |-
Returns all policy entries of the policy identified by the `policyId`
path parameter.
tags:
- Policies
parameters:
- $ref: '#/components/parameters/PolicyIdPathParam'
- $ref: '#/components/parameters/IfMatchHeaderParamHash'
- $ref: '#/components/parameters/IfNoneMatchHeaderParam'
- $ref: '#/components/parameters/TimeoutParam'
responses:
'200':
description: |-
The request successfully returned completed and returned are the
policy entries.
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/PolicyEntries'
'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: Modify the entries of a specific policy
description: |-
Modify the policy entries of the policy identified by the `policyId`
path parameter.
Note: Take care to not lock yourself out. Use the placeholder {{ request:subjectId }}
in order to let the backend insert the authenticated subjectId of the HTTP request.
tags:
- Policies
parameters:
- $ref: '#/components/parameters/PolicyIdPathParam'
- $ref: '#/components/parameters/IfMatchHeaderParamHash'
- $ref: '#/components/parameters/IfNoneMatchHeaderParam'
- $ref: '#/components/parameters/TimeoutParam'
- $ref: '#/components/parameters/ResponseRequiredParam'
responses:
'204':
description: The policy entries 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 `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 `policy:/entries` resource,
without any revoke in a deeper path of the policy resource.
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/PolicyEntries'
example:
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 entries.
Use the placeholder `{{ request:subjectId }}` in order to let the
backend insert the authenticated subjectId of the HTTP request.
required: true
'/policies/{policyId}/entries/{label}':
get:
summary: Retrieve the entries of a specific Label of a specific policy
description: |-
Returns all entries (subjects, resources, etc.) of the policy identified by the `policyId` path
parameter, and by the `label` path parameter.
Example label: DEFAULT.
tags:
- Policies
parameters:
- $ref: '#/components/parameters/PolicyIdPathParam'
- $ref: '#/components/parameters/LabelPathParam'
- $ref: '#/components/parameters/IfMatchHeaderParamHash'
- $ref: '#/components/parameters/IfNoneMatchHeaderParam'
- $ref: '#/components/parameters/TimeoutParam'
responses:
'200':
description: |-
The request successfully returned completed and returned is the
policy entry.
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/PolicyEntry'
'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 or
the policy entry 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 modify the entries of a specific Label of a specific policy
description: |-
Create or modify the policy entry identified by the
`policyId` path parameter and with the label identified by the `label`
path parameter.
* If you specify a new label, the respective policy entry will be created
* If you specify an existig label, the respective policy entry will be updated
tags:
- Policies
parameters:
- $ref: '#/components/parameters/PolicyIdPathParam'
- $ref: '#/components/parameters/LabelPathParam'
- $ref: '#/components/parameters/IfMatchHeaderParamHash'
- $ref: '#/components/parameters/IfNoneMatchHeaderParam'
- $ref: '#/components/parameters/TimeoutParam'
- $ref: '#/components/parameters/ResponseRequiredParam'
responses:
'201':
description: The policy entry 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 entry
schema:
type: string
content:
application/json:
schema:
$ref: '#/components/schemas/PolicyEntry'
'204':
description: The policy entry 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 entry 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 `policy:/entries/{label}` resource,
without any revoke in a deeper path of the policy resource.
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/PolicyEntry'
example:
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 entry.
Use the placeholder `{{ request:subjectId }}` in order to let the
backend insert the authenticated subjectId of the HTTP request.
### Example
Given your policy "com.acme.coffeemaker:policy-01" only has the
DEFAULT entry, and you want to add a "Consumer" section which additionally allows USER-01
(managed within a Nginx reverse proxy) to
*read* the thing and to trigger a "makeCoffee" operation (i.e. POST such a message - see
POST /things/{thingId}/inbox/messages/{messageSubject}).
Set the label value to **Consumer** and the following request body:
```
{
"subjects": {
"nginx:USER-01": {
"type": "pre authenticated user from nginx"
}
},
"resources": {
"thing:/": {
"grant": [
"READ"
],
"revoke": []
},
"message:/": {
"grant": [
"WRITE"
],
"revoke": []
}
}
}
```
required: true
delete:
summary: Delete the entries of a specific Label of a specific policy
description: |-
Deletes the entry of the policy identified by the `policyId` path
parameter and with the label identified by the `label` path parameter.
tags:
- Policies
parameters:
- $ref: '#/components/parameters/PolicyIdPathParam'
- $ref: '#/components/parameters/LabelPathParam'
- $ref: '#/components/parameters/IfMatchHeaderParamHash'
- $ref: '#/components/parameters/IfNoneMatchHeaderParam'
- $ref: '#/components/parameters/TimeoutParam'
- $ref: '#/components/parameters/ResponseRequiredParam'
responses:
'204':
description: The policy entry 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 `policy:/entries/{label}` resource,
without any revoke in a deeper path of the policy resource.
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/{label}/actions/activateTokenIntegration':
post:
summary: Activate a subject for this policy entry derived from the token
description: |-
**This action only works when authenticated with a Json Web Token (JWT).**
Based on the authenticated token (JWT), **this policy entry** is checked to match those conditions:
* the authenticated token is granted the `EXECUTE` permission to perform the `activateTokenIntegration` action
* one of the subject IDs is contained in the authenticated token
* at least one `READ` permission to a `thing:/` resource path is granted
When all conditions match, a new subject is **injected into this policy entry** calculated with information
extracted from the authenticated JWT.
The injected subjects expire when the JWT expires.
tags:
- Policies
parameters:
- $ref: '#/components/parameters/PolicyIdPathParam'
- $ref: '#/components/parameters/LabelPathParam'
responses:
'204':
description: The request was successful. The subject was injected.
'400':
description: The request could not be completed because the authentication was not performed with a JWT.
'403':
description: |-
The request could not be completed because the authenticated JWT did not have the `EXECUTE` permission on this
policy entry.
'404':
description: |-
The request could not be completed because this policy entry did not match the following conditions:
* containing a a subject ID matching the JWT's authenticated subject
* containing a `READ` permission granted to a `thing:/` resource path
requestBody:
$ref: '#/components/requestBodies/ActivateTokenIntegration'
'/policies/{policyId}/entries/{label}/actions/deactivateTokenIntegration':
post:
summary: Deactivate a subject for this policy entry derived from the token
description: |-
**This action only works when authenticated with a Json Web Token (JWT).**
Based on the authenticated token (JWT), **this policy entry** is checked to match those conditions:
* the authenticated token is granted the `EXECUTE` permission to perform the `deactivateTokenIntegration` action
* one of the subject IDs is contained in the authenticated token
When all conditions match, the calculated subject with information extracted from the authenticated JWT is **removed
from this policy entry**.
tags:
- Policies
parameters:
- $ref: '#/components/parameters/PolicyIdPathParam'
- $ref: '#/components/parameters/LabelPathParam'
responses:
'204':
description: The request was successful. The subject was removed.
'400':
description: The request could not be completed because the authentication was not performed with a JWT.
'403':
description: The request could not be completed because the user did not have the `EXECUTE` permission on this policy entry.
'404':
description: |-
The request could not be completed because this policy entry did not match the following conditions:
* containing a a subject ID matching the JWT's authenticated subject
'/policies/{policyId}/entries/{label}/subjects':
get:
summary: Retrieve all Subjects for a specific Label of a specific policy
description: |-
Returns all subject entries of the policy identified by the
`policyId` path parameter, and by the `label`
path parameter.
tags:
- Policies
parameters:
- $ref: '#/components/parameters/PolicyIdPathParam'
- $ref: '#/components/parameters/LabelPathParam'
- $ref: '#/components/parameters/IfMatchHeaderParamHash'
- $ref: '#/components/parameters/IfNoneMatchHeaderParam'
- $ref: '#/components/parameters/TimeoutParam'
responses:
'200':
description: The request successfully returned. The subjects are returned.
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/Subjects'
'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 or
the policy entry 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 modify all Subjects for a specific Label of a specific policy
description: |-
Create or modify at once ALL subjects of the policy entry identified
by the `policyId` path parameter, and by the `label` path parameter.
### Example - delete all subjects
To delete all subjects set an empty body { }
### Example - entities authenticated by nginx
To add a user authenticated via pre-authentication at nginx:
```
{
"nginx:ID-user": {
"type": "pre authenticated user from nginx"
}
}
```
tags:
- Policies
parameters:
- $ref: '#/components/parameters/PolicyIdPathParam'
- $ref: '#/components/parameters/LabelPathParam'
- $ref: '#/components/parameters/IfMatchHeaderParamHash'
- $ref: '#/components/parameters/IfNoneMatchHeaderParam'
- $ref: '#/components/parameters/TimeoutParam'
- $ref: '#/components/parameters/ResponseRequiredParam'
responses:
'204':
description: The Subjects were successfully created or 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 subjects 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 `policy:/entries/{label}/subjects` resource,
without any revoke in a deeper path of the policy resource.
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/Subjects'
description: |-
JSON representation of the Subjects.
Use the placeholder `{{ request:subjectId }}` in order to let the
backend insert the authenticated subjectId of the HTTP request.
required: true
'/policies/{policyId}/entries/{label}/subjects/{subjectId}':
get:
summary: Retrieve one specific Subject for a specific Label of a specific policy
description: |-
Returns the subject with ID `subjectId` of the policy entry identified
by the `policyId` path parameter, and by the `label` path parameter.
tags:
- Policies
parameters:
- $ref: '#/components/parameters/PolicyIdPathParam'
- $ref: '#/components/parameters/LabelPathParam'
- $ref: '#/components/parameters/SubjectIdPathParam'
- $ref: '#/components/parameters/IfMatchHeaderParamHash'
- $ref: '#/components/parameters/IfNoneMatchHeaderParam'
- $ref: '#/components/parameters/TimeoutParam'
responses:
'200':
description: |-
The request successfully returned completed and returned is the
Subject.
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/SubjectEntry'
'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,
the policy entry or the Subject 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 modify one specific Subject for a specific Label of a specific policy
description: |-
Create or modify the subject with ID `subjectId` of the policy identified
by the `policyId` path parameter, and by the `label` path parameter.
tags:
- Policies
parameters:
- $ref: '#/components/parameters/PolicyIdPathParam'
- $ref: '#/components/parameters/LabelPathParam'
- $ref: '#/components/parameters/SubjectIdPathParam'
- $ref: '#/components/parameters/IfMatchHeaderParamHash'
- $ref: '#/components/parameters/IfNoneMatchHeaderParam'
- $ref: '#/components/parameters/TimeoutParam'
- $ref: '#/components/parameters/ResponseRequiredParam'
responses:
'201':
description: The Subject 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 Subject
schema:
type: string
content:
application/json:
schema:
$ref: '#/components/schemas/SubjectEntry'
'204':
description: The Subject 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 subject 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:/entries/{label}/subjects/{subjectId}` resource,
without any revoke in a deeper path of the policy resource.
content:
application/json:
schema:
$ref: '#/components/schemas/AdvancedError'
'404':
description: |-
The request could not be completed. The policy with the given ID or
the policy entry 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/SubjectEntry'
description: JSON representation of the Subject
required: true
delete:
summary: Delete one specific Subject for a specific Label of a specific policy
description: |-
Deletes the subject with ID `subjectId` from the policy identified
by the `policyId` path parameter and
by the `label` path parameter.
Note: If the subject is used in other labels, it will not be deleted there,
i.e. it will not lose those permissions, but only the permissions defined in the
label specified at this path.
tags:
- Policies
parameters:
- $ref: '#/components/parameters/PolicyIdPathParam'
- $ref: '#/components/parameters/LabelPathParam'
- $ref: '#/components/parameters/SubjectIdPathParam'
- $ref: '#/components/parameters/IfMatchHeaderParamHash'
- $ref: '#/components/parameters/IfNoneMatchHeaderParam'
- $ref: '#/components/parameters/TimeoutParam'
- $ref: '#/components/parameters/ResponseRequiredParam'
responses:
'204':
description: The Subject 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:/entries/{label}/subjects/{subjectId}` resource,
without any revoke in a deeper path of the policy resource.
content:
application/json:
schema:
$ref: '#/components/schemas/AdvancedError'
'404':
description: |-
The request could not be completed. The policy with the given ID,
the policy entry or the Subject 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/{label}/resources':
get:
summary: Retrieve all Resources for a specific Label of a specific policy
description: |-
Returns all resource entries of the policy identified by
the `policyId` path parameter,
and by the `label` path parameter.
tags:
- Policies
parameters:
- $ref: '#/components/parameters/PolicyIdPathParam'
- $ref: '#/components/parameters/LabelPathParam'
- $ref: '#/components/parameters/IfMatchHeaderParamHash'
- $ref: '#/components/parameters/IfNoneMatchHeaderParam'
- $ref: '#/components/parameters/TimeoutParam'
responses:
'200':
description: The request successfully returned. The resources are returned.
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/Resources'
'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 or
the policy entry 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 modify all Resources for a specific Label of a specific policy
description: |-
Create or modify all resources of the policy
identified by the `policyId` path parameter,
and by the `label` path parameter.
### Delete all resource entries
Set the empty body part, if you need to delete all resource entries: { }
### Set max permissions on all ressources
```
{
"policy:/": {
"grant": [
"READ",
"WRITE"
],
"revoke": []
},
"thing:/": {
"grant": [
"READ",
"WRITE"
],
"revoke": []
},
"message:/": {
"grant": [
"READ",
"WRITE"
],
"revoke": []
}
}
```
### Allow to read all parts of a thing except the "confidential" feature
```
{
"thing:/": {
"grant": [
"READ"
],
"revoke": []
},
"things:/features/confidential": {
"grant": [],
"revoke": [
"READ"
]
}
}
```
tags:
- Policies
parameters:
- $ref: '#/components/parameters/PolicyIdPathParam'
- $ref: '#/components/parameters/LabelPathParam'
- $ref: '#/components/parameters/IfMatchHeaderParamHash'
- $ref: '#/components/parameters/IfNoneMatchHeaderParam'
- $ref: '#/components/parameters/TimeoutParam'
- $ref: '#/components/parameters/ResponseRequiredParam'
responses:
'204':
description: The Resources were successfully created or 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 is invalid, or no valid Resources 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.
You need `WRITE` permission on the root `policy:/entries/{label}/resources` resource,
without any revoke in a deeper path of the policy resource.
content:
application/json:
schema:
$ref: '#/components/schemas/AdvancedError'
'404':
description: |-
The request could not be completed. The policy with the given ID or
the policy entry 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/Resources'
description: JSON representation of the Resources
required: true
'/policies/{policyId}/entries/{label}/resources/{resourcePath}':
get:
summary: Retrieve one specific Resource for a specific Label of a specific policy
description: |-
Returns the resource with path `resourcePath` of the policy identified
by the `policyId` path parameter, and
by the `label` path parameter.
tags:
- Policies
parameters:
- $ref: '#/components/parameters/PolicyIdPathParam'
- $ref: '#/components/parameters/LabelPathParam'
- $ref: '#/components/parameters/ResourcePathPathParam'
- $ref: '#/components/parameters/IfMatchHeaderParamHash'
- $ref: '#/components/parameters/IfNoneMatchHeaderParam'
- $ref: '#/components/parameters/TimeoutParam'
responses:
'200':
description: |-
The request successfully returned completed and returned is the
Resource.
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/ResourceEntry'
'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,
the policy entry or the Resource 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 modify one specific Resource for a specific Label of a specific policy
description: |-
Create or modify the Resource with path `resourcePath` of the policy
entry identified by the `label` path parameter belonging to the policy
identified by the `policyId` path parameter.
tags:
- Policies
parameters:
- $ref: '#/components/parameters/PolicyIdPathParam'
- $ref: '#/components/parameters/LabelPathParam'
- $ref: '#/components/parameters/ResourcePathPathParam'
- $ref: '#/components/parameters/IfMatchHeaderParamHash'
- $ref: '#/components/parameters/IfNoneMatchHeaderParam'
- $ref: '#/components/parameters/TimeoutParam'
- $ref: '#/components/parameters/ResponseRequiredParam'
responses:
'201':
description: The Resource 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 Resource
schema:
type: string
content:
application/json:
schema:
$ref: '#/components/schemas/ResourceEntry'
'204':
description: The Resource 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
'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))
* the JSON is invalid, or no valid Resource 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.
You need `WRITE` permission on the `policy:/entries/{label}/resources/{resourcePath}` resource,
without any revoke in a deeper path of the policy resource.
content:
application/json:
schema:
$ref: '#/components/schemas/AdvancedError'
'404':
description: |-
The request could not be completed. The policy with the given ID or
the policy entry 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/ResourceEntry'
description: JSON representation of the Resource
required: true
delete:
summary: Delete one specific Resource for a specific Label of a specific policy
description: |-
Deletes the resource with path `resourcePath` from the policy
identified by the the `policyId` path parameter, and by the
`label` path parameter.
tags:
- Policies
parameters:
- $ref: '#/components/parameters/PolicyIdPathParam'
- $ref: '#/components/parameters/LabelPathParam'
- $ref: '#/components/parameters/ResourcePathPathParam'
- $ref: '#/components/parameters/IfMatchHeaderParamHash'
- $ref: '#/components/parameters/IfNoneMatchHeaderParam'
- $ref: '#/components/parameters/TimeoutParam'
- $ref: '#/components/parameters/ResponseRequiredParam'
responses:
'204':
description: The Resource 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 `policy:/entries/{label}/resources/{resourcePath}` resource,
without any revoke in a deeper path of the policy resource.
content:
application/json:
schema:
$ref: '#/components/schemas/AdvancedError'
'404':
description: |-
The request could not be completed. The policy with the given ID,
the policy entry or the Resource was not found in the context of the
authenticated user.
content:
application/json:
schema:
$ref: '#/components/schemas/AdvancedError'
'412':
$ref: '#/components/responses/PreconditionFailed'
/whoami:
get:
summary: Retrieve information about the current caller
description: 'Get information about the current caller, e.g. the auth subjects that are generated for the caller.'
tags:
- Policies
responses:
'200':
description: The request successfully returned information about the caller.
content:
application/json:
schema:
$ref: '#/components/schemas/WhoAmI'
'401':
description: The request could not be completed due to missing authentication.
content:
application/json:
schema:
$ref: '#/components/schemas/AdvancedError'
/search/things:
get:
summary: Search for things
description: |-
This resource can be used to search for things.
* The query parameter `filter` is not mandatory. If it is not set, the
result contains all things which the logged in user is allowed to read.
* The search is case sensitive. In case you don't know how exactly the
spelling of value of the namespace, name, attribute, feature etc. is, use the *like*
notation instead of *eq* for filtering.
* The resource supports sorting and paging. If paging is not explicitly
specified by means of the `size` option, a default count of `25`
documents is returned.
* The internal search index is "eventually consistent". Consistency with the latest
thing updates should recover within milliseconds.
parameters:
- $ref: '#/components/parameters/SearchFilter'
- $ref: '#/components/parameters/NamespacesFilter'
- $ref: '#/components/parameters/ThingFieldsQueryParam'
- $ref: '#/components/parameters/TimeoutParam'
- name: option
in: query
description: |-
Possible values for the parameter:
#### Sort operations
* ```sort([+|-]{property})```
* ```sort([+|-]{property},[+|-]{property},...)```
#### Paging operations
* ```size({page-size})``` Maximum allowed page size is `200`. Default page size is `25`.
* ```cursor({cursor-id})``` Start the search from the cursor location. Specify the cursor ID without
quotation marks. Cursor IDs are given in search responses and mark the position after the last entry of
the previous search. The meaning of cursor IDs is unspecified and may change without notice.
The paging option `limit({offset},{count})` is deprecated.
It may result in slow queries or timeouts and will be removed eventually.
#### Examples:
* ```sort(+thingId)```
* ```sort(-attributes/manufacturer)```
* ```sort(+thingId,-attributes/manufacturer)```
* ```size(10)``` return 10 results
* ```cursor(LOREMIPSUM)``` return results after the position of the cursor `LOREMIPSUM`.
#### Combine:
If you need to specify multiple options, when using the swagger UI just write each option in a new line.
When using the plain REST API programmatically,
you will need to separate the options using a comma (,) character.
```size(200),cursor(LOREMIPSUM)```
The deprecated paging option `limit` may not be combined with the other paging options `size` and `cursor`.
required: false
schema:
type: string
tags:
- Things-Search
responses:
'200':
description: An array of the matching things.
content:
application/json:
schema:
$ref: '#/components/schemas/SearchResultThings'
'400':
description: |-
The request could not be completed. A provided parameter is in a
wrong format.
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 due to an invalid authentication.
content:
application/json:
schema:
$ref: '#/components/schemas/AdvancedError'
'504':
description: The request ran out of time to execute on the the back-end. Optimize your query and try again.
content:
application/json:
schema:
$ref: '#/components/schemas/AdvancedError'
/search/things/count:
get:
summary: Count things
description: |-
This resource can be used to count things.
The query parameter `filter` is not mandatory. If it is not set there is
returned the total amount of things which the logged in user is allowed
to read.
To search for nested properties, we use JSON Pointer notation
(RFC-6901). See the following example how to search for the sub property
`location` of the parent property `attributes` with a forward slash as
separator:
```eq(attributes/location,"kitchen")```
parameters:
- $ref: '#/components/parameters/SearchFilter'
- $ref: '#/components/parameters/NamespacesFilter'
- $ref: '#/components/parameters/TimeoutParam'
tags:
- Things-Search
responses:
'200':
description: A number indicating the amount of matched things
content:
application/json:
schema:
type: integer
'400':
description: |-
The request could not be completed. A provided parameter is in a
wrong format.
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 due to an invalid authentication.
content:
application/json:
schema:
$ref: '#/components/schemas/AdvancedError'
'504':
description: The request ran out of time to execute on the the back-end. Optimize your query and try again.
content:
application/json:
schema:
$ref: '#/components/schemas/AdvancedError'
/cloudevents:
post:
summary: Processes a CloudEvent sent in Ditto Protocol
description: |-
Provides an endpoint accepting [CloudEvents via its HTTP protocol binding](https://github.com/cloudevents/spec/blob/v1.0/http-protocol-binding.md)
in [Ditto Protocol JSON](https://www.eclipse.org/ditto/protocol-specification.html).
The endpoint can also directly be configured as a [Knative eventing](https://knative.dev/docs/eventing/) destination.
Find more documentation on that [here](https://www.eclipse.org/ditto/httpapi-protocol-bindings-cloudevents.html).
tags:
- CloudEvents
parameters:
- in: header
name: ce-specversion
description: The CloudEvents "specversion".
schema:
type: string
example: '1.0'
required: true
- in: header
name: ce-type
description: The CloudEvents event "type".
schema:
type: string
example: com.example.someevent
required: true
- in: header
name: ce-source
description: The CloudEvents event "source".
schema:
type: string
example: /mycontext
required: true
- in: header
name: ce-id
description: The CloudEvents event "id".
schema:
type: string
example: 1234-1234-1234
required: true
- in: header
name: ce-time
description: The CloudEvents event "time".
schema:
type: string
format: date-time
example: '2020-12-31T23:59:59Z'
required: true
- in: header
name: ce-dataschema
description: 'The CloudEvents event "dataschema". If provided, this must start with `ditto:`.'
schema:
type: string
required: false
responses:
'202':
description: 'The Ditto Protocol CloudEvent was successfully parsed, the authentication was valid and also reached the persistence.'
'400':
description: |-
The request could not be completed. Possible reasons:
* the CloudEvent could not be parsed as some mandatory CloudEvent headers were missing from the request
* the payload was missing from the CloudEvent
* the [Ditto Protocol JSON](https://www.eclipse.org/ditto/protocol-specification.html) message could not be parsed or was missing a required field
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.
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 perform the contained Ditto Protocol command.
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'
'415':
description: The `Content-Type` of the request was not supported.
content:
application/json:
schema:
$ref: '#/components/schemas/AdvancedError'
requestBody:
content:
application/vnd.eclipse.ditto+json:
schema:
type: object
properties:
topic:
type: string
description: |-
Contains information about the contents of the payload:
* the affected Thing (namespace and Thing ID)
* the type of operation (command/event, create/retrieve/modify/delete)
example: org.eclipse.ditto/thing-1/things/twin/commands/modify
headers:
type: object
description: Additional headers.
properties:
correlation-id:
type: string
description: |-
The correlation-id header is used for linking one message with another.
It typically links a reply message with its requesting message.
example:
correlation-id: 1234-4321-1234
path:
type: string
description: References the part of a Thing which is affected by this message.
example: /features/location/properties/longitude
value:
oneOf:
- type: object
- type: string
- type: number
- type: array
- type: boolean
description: The `value` field contains the actual payload e.g. a sensor value.
required:
- topic
- path
example:
topic: org.eclipse.ditto/thing-1/things/twin/commands/modify
path: /
value:
attributes:
foo: 42
description: |-
The [Ditto Protocol JSON](https://www.eclipse.org/ditto/protocol-specification.html) payload defining which
command to process.
components:
requestBodies:
Attributes:
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
Definition:
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: `""`
Payload:
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.
Value:
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
ActivateTokenIntegration:
content:
application/json:
schema:
properties:
announcement:
$ref: '#/components/schemas/SubjectAnnouncement'
example:
announcement:
beforeExpiry: 5m
whenDeleted: true
description: Optional request payload for `activateTokenIntegration` policy action.
required: false
responses:
EntityTooLarge:
description: The created or modified entity is larger than the accepted limit of 100 kB.
content:
application/json:
schema:
$ref: '#/components/schemas/AdvancedError'
MessageTimeout:
description: The request could not be completed as there is no consumer for this message connected.
content:
application/json:
schema:
$ref: '#/components/schemas/AdvancedError'
MessageTooLarge:
description: The size of the send message is larger than the accepted limit of 250 kB.
content:
application/json:
schema:
$ref: '#/components/schemas/AdvancedError'
NotModified:
description: |-
The (sub-)resource has not been modified. This happens when you specified a If-None-Match header which
matches the current ETag of the (sub-)resource.
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
PreconditionFailed:
description: |-
A precondition for reading or writing the (sub-)resource failed. This will happen for write requests, if you
specified an If-Match or If-None-Match header, which fails the precondition check against the current ETag of
the (sub-)resource. For read requests, this error may only happen for a failing If-Match header. In case of a
failing If-None-Match header for a read request, status 304 will be returned instead.
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/AdvancedError'
parameters:
AllowPolicyLockoutParam:
name: allow-policy-lockout
in: query
description: |-
Defines whether a subject is allowed to create a policy without having WRITE permission on the policy
resource of the created policy.
The default (if ommited) is `false`.
required: false
schema:
type: boolean
AttributesPathPathParam:
name: attributePath
in: path
description: 'The path to the attribute, e.g. **manufacturer/name**'
required: true
schema:
type: string
AttributesFieldsQueryParam:
name: fields
in: query
description: |-
Contains a comma-separated list of fields from the attributes to be
included in the returned JSON.
#### Selectable fields
Supports selecting arbitrary sub-fields as defined in the attributes by
using a comma-separated list:
* several properties paths can be passed as a comma-separated list of JSON pointers (RFC-6901)
For example:
* `?fields=model` would select only `model` attribute value (if present)
* `?fields=model,make` would select `model` and `make` attribute values (if present)
Supports selecting arbitrary sub-fields of objects by wrapping sub-fields
inside parentheses `( )`:
* a comma-separated list of sub-fields (a sub-field is a JSON pointer (RFC-6901) separated with `/`) to select
* sub-selectors can be used to request only specific sub-fields by placing expressions in parentheses `( )` after a selected subfield
For example:
* `?fields=location(longitude,latitude)` would select the `longitude` and `latitude` value inside the `location` attribute
#### Examples
* `?fields=model,make,location(longitude,latitude)`
* `?fields=listOfAddresses/postal(city,street))`
required: false
schema:
type: string
DesiredPropertiesFieldsQueryParam:
name: fields
in: query
description: |-
Contains a comma-separated list of fields from the desiredProperties to be
included in the returned JSON.
#### Selectable fields
Supports selecting arbitrary sub-fields as defined in the desiredProperties by
using a comma-separated list:
* several desiredProperties paths can be passed as a comma-separated list of JSON pointers (RFC-6901)
For example:
* `?fields=temperature` would select only `temperature` property value of desiredProperties (if present)
* `?fields=temperature,humidity` would select only `temperature` and `humidity` property values of desiredProperties (if present)
Supports selecting arbitrary sub-fields of objects by wrapping sub-fields
inside parentheses `( )`:
* a comma-separated list of sub-fields (a sub-field is a JSON pointer (RFC-6901) separated with `/`) to select
* sub-selectors can be used to request only specific sub-fields by placing expressions in parentheses `( )` after a selected subfield
For example:
* `?fields=location(longitude,latitude)` would select the `longitude` and `latitude` value inside the `location` property of desiredProperties
#### Examples
* `?fields=temperature,humidity,location(longitude,latitude)`
* `?fields=configuration,status(powerConsumption/watts)`
required: false
schema:
type: string
FeatureFieldsQueryParam:
name: fields
in: query
description: |-
Contains a comma-separated list of fields from the selected feature to be
included in the returned JSON.
#### Selectable fields
* `properties`
Supports selecting arbitrary sub-fields by using a comma-separated list:
* several properties paths can be passed as a comma-separated list of JSON pointers (RFC-6901)
For example:
* `?fields=properties/color` would select only `color` property value (if present)
* `?fields=properties/color,properties/brightness` would select only `color` and `brightness` property values (if present)
Supports selecting arbitrary sub-fields of objects by wrapping sub-fields inside parentheses `( )`:
* a comma-separated list of sub-fields (a sub-field is a JSON pointer (RFC-6901) separated with `/`) to select
* sub-selectors can be used to request only specific sub-fields by placing expressions in parentheses `( )` after a selected subfield
For example:
* `?fields=properties(color,brightness)` would select only `color` and `brightness` property values (if present)
* `?fields=properties(location/longitude)` would select the `longitude` value inside the `location` object
#### Examples
* `?fields=properties(color,brightness)`
required: false
schema:
type: string
FeatureIdPathPathParam:
name: featureId
in: path
description: The ID of the feature - has to conform to RFC-3986 (URI)
required: true
schema:
type: string
FeaturesFieldsQueryParam:
name: fields
in: query
description: |-
Contains a comma-separated list of fields from one or more features to be
included in the returned JSON.
#### Selectable fields
* `{featureId}` The ID of the feature to select properties in
* `properties`
Supports selecting arbitrary sub-fields by using a comma-separated list:
* several properties paths can be passed as a comma-separated list of JSON pointers (RFC-6901)
For example:
* `?fields={featureId}/properties/color` would select only `color` property value (if present) of the feature identified with `{featureId}`
* `?fields={featureId}/properties/color,properties/brightness` would select only `color` and `brightness` property values (if present) of the feature identified with `{featureId}`
Supports selecting arbitrary sub-fields of objects by wrapping sub-fields inside parentheses `( )`:
* a comma-separated list of sub-fields (a sub-field is a JSON pointer (RFC-6901) separated with `/`) to select
* sub-selectors can be used to request only specific sub-fields by placing expressions in parentheses `( )` after a selected subfield
For example:
* `?fields={featureId}/properties(color,brightness)` would select only `color` and `brightness` property values (if present) of the feature identified with `{featureId}`
* `?fields={featureId}/properties(location/longitude)` would select the `longitude` value inside the `location` object of the feature identified with `{featureId}`
#### Examples
* `?fields=EnvironmentScanner/properties(temperature,humidity)`
* `?fields=EnvironmentScanner/properties(temperature,humidity),Vehicle/properties/configuration`
required: false
schema:
type: string
IfMatchHeaderParam:
name: If-Match
in: header
description: |-
The `If-Match` header, which has to conform to RFC-7232 (Conditional Requests). Common usages are:
* optimistic locking by specifying the `ETag` from a previous GET response, e.g. `If-Match: "rev:4711"`
* retrieving or modifying a resource only if it already exists, e.g. `If-Match: *`
required: false
schema:
type: string
IfMatchHeaderParamHash:
name: If-Match
in: header
description: |-
The `If-Match` header which has to conform to RFC-7232 (Conditional Requests). Common usages are:
* optimistic locking by specifying the `ETag` from a previous HTTP response, e.g. `If-Match: "hash:a75ece4e"`
* retrieving or modifying a resource only if it already exists, e.g. `If-Match: *`
required: false
schema:
type: string
IfNoneMatchHeaderParam:
name: If-None-Match
in: header
description: 'The `If-None-Match` header, which has to conform to RFC-7232 (Conditional Requests). A common usage scenario is to modify a resource only if it does not yet exist, thus to create it, by specifying `If-None-Match: *`.'
required: false
schema:
type: string
LabelPathParam:
name: label
in: path
description: The label of a policy entry
required: true
schema:
type: string
LiveMessageRequestedAcksParam:
name: requested-acks
in: query
description: |-
Contains the "requested acknowledgements" for this request as comma separated list. The HTTP call will
block until all requested acknowledgements were aggregated or will time out based on the specified `timeout`
parameter.
The default (if omitted) requested acks is `requested-acks=live-response` which will block the
HTTP call until a subscriber of the live message sends a response.
required: false
schema:
type: string
MessageClaimTimeoutParam:
name: timeout
in: query
description: |-
Contains an optional timeout (in seconds) of how long to wait for the Claim response and therefore block the
HTTP request. Default value (if omitted): 60 seconds. Maximum value: 600 seconds. A value of 0 seconds applies
fire and forget semantics for the message.
required: false
schema:
type: integer
MessageSubjectPathParam:
name: messageSubject
in: path
description: The subject of the Message - has to conform to RFC-3986 (URI)
required: true
schema:
type: string
MessageTimeoutParam:
name: timeout
in: query
description: |-
Contains an optional timeout (in seconds) of how long to wait for the message response and therefore block the
HTTP request. Default value (if omitted): 10 seconds. Maximum value: 60 seconds. A value of 0 seconds applies
fire and forget semantics for the message.
required: false
schema:
type: integer
NamespacesFilter:
name: namespaces
in: query
description: |-
A comma-separated list of namespaces. This list is used to limit the query to things in the given namespaces
only.
#### Examples:
* `?namespaces=com.example.namespace`
* `?namespaces=com.example.namespace1,com.example.namespace2`
required: false
schema:
type: string
PolicyIdPathParam:
name: policyId
in: path
description: |-
The ID of the policy needs to follow 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 namespace needs to:
* conform to the reverse domain name notation
required: true
schema:
type: string
PropertiesFieldsQueryParam:
name: fields
in: query
description: |-
Contains a comma-separated list of fields from the properties to be
included in the returned JSON.
#### Selectable fields
Supports selecting arbitrary sub-fields as defined in the properties by
using a comma-separated list:
* several properties paths can be passed as a comma-separated list of JSON pointers (RFC-6901)
For example:
* `?fields=temperature` would select only `temperature` property value (if present)
* `?fields=temperature,humidity` would select only `temperature` and `humidity` property values (if present)
Supports selecting arbitrary sub-fields of objects by wrapping sub-fields
inside parentheses `( )`:
* a comma-separated list of sub-fields (a sub-field is a JSON pointer (RFC-6901) separated with `/`) to select
* sub-selectors can be used to request only specific sub-fields by placing expressions in parentheses `( )` after a selected subfield
For example:
* `?fields=location(longitude,latitude)` would select the `longitude` and `latitude` value inside the `location` property
#### Examples
* `?fields=temperature,humidity,location(longitude,latitude)`
* `?fields=configuration,status(powerConsumption/watts)`
required: false
schema:
type: string
PropertyPathPathParam:
name: propertyPath
in: path
description: The path to the property
required: true
schema:
type: string
PutMetadataParam:
name: put-metadata
in: header
description: 'The `put-metadata` header, which sets Metadata information in the Thing.'
required: false
schema:
type: array
description: An array of objects containing metadata to apply.
items:
type: object
description: Object containing a `key` where to apply the metadata and a `value` with the metadata value to apply.
additionalProperties:
properties:
key:
type: string
description: The JsonPointer to set the metadata `value` to. May start with `*/<key>` in order to apply the metadata to all affected JSON leaves.
value:
description: The arbitrary JSON value to set as metadata.
RequestedAcksParam:
name: requested-acks
in: query
description: |-
Contains the "requested acknowledgements" for this modifying request as comma separated list. The HTTP call will
block until all requested acknowledgements were aggregated or will time out based on the specified `timeout`
parameter.
The default (if omitted) requested acks is `requested-acks=twin-persisted` which will block the
HTTP call until the change was persited to the twin.
required: false
schema:
type: string
ResourcePathPathParam:
name: resourcePath
in: path
description: The path of an (Authorization) Resource
required: true
schema:
type: string
ResponseRequiredParam:
name: response-required
in: query
description: |-
Defines whether a response is required to the API call or not - if set to `false` the response will directly
sent back with a status code of `202` (Accepted).
The default (if ommited) response is `true`.
required: false
schema:
type: boolean
SearchFilter:
name: filter
in: query
description: |-
#### Filter predicates:
* ```eq({property},{value})``` (i.e. equal to the given value)
* ```ne({property},{value})``` (i.e. not equal to the given value)
* ```gt({property},{value})``` (i.e. greater than the given value)
* ```ge({property},{value})``` (i.e. equal to the given value or greater than it)
* ```lt({property},{value})``` (i.e. lower than the given value or equal to it)
* ```le({property},{value})``` (i.e. lower than the given value)
* ```in({property},{value},{value},...)``` (i.e. contains at least one of the values listed)
* ```like({property},{value})``` (i.e. contains values similar to the expressions listed)
* ```exists({property})``` (i.e. all things in which the given path exists)
Note: When using filter operations, only things with the specified properties are returned.
For example, the filter `ne(attributes/owner, "SID123")` will only return things that do have
the `owner` attribute.
#### Logical operations:
* ```and({query},{query},...)```
* ```or({query},{query},...)```
* ```not({query})```
#### Examples:
* ```eq(attributes/location,"kitchen")```
* ```ge(thingId,"myThing1")```
* ```gt(_created,"2020-08-05T12:17")```
* ```exists(features/featureId)```
* ```and(eq(attributes/location,"kitchen"),eq(attributes/color,"red"))```
* ```or(eq(attributes/location,"kitchen"),eq(attributes/location,"living-room"))```
* ```like(attributes/key1,"known-chars-at-start*")```
* ```like(attributes/key1,"*known-chars-at-end")```
* ```like(attributes/key1,"*known-chars-in-between*")```
* ```like(attributes/key1,"just-som?-char?-unkn?wn")```
The `like` filters with the wildcard `*` at the beginning can slow down your search request.
required: false
schema:
type: string
SubjectIdPathParam:
name: subjectId
in: path
description: The ID of an (Authorization) Subject
required: true
schema:
type: string
ThingFieldsQueryParam:
name: fields
in: query
description: |-
Contains a comma-separated list of fields to be included in the returned
JSON. attributes can be selected in the same manner.
#### Selectable fields
* `thingId`
* `policyId`
* `definition`
* `attributes`
Supports selecting arbitrary sub-fields by using a comma-separated list:
* several attribute paths can be passed as a comma-separated list of JSON pointers (RFC-6901)
For example:
* `?fields=attributes/model` would select only `model` attribute value (if present)
* `?fields=attributes/model,attributes/location` would select only `model` and
`location` attribute values (if present)
Supports selecting arbitrary sub-fields of objects by wrapping sub-fields inside parentheses `( )`:
* a comma-separated list of sub-fields (a sub-field is a JSON pointer (RFC-6901)
separated with `/`) to select
* sub-selectors can be used to request only specific sub-fields by placing expressions
in parentheses `( )` after a selected subfield
For example:
* `?fields=attributes(model,location)` would select only `model`
and `location` attribute values (if present)
* `?fields=attributes(coffeemaker/serialno)` would select the `serialno` value
inside the `coffeemaker` object
* `?fields=attributes/address/postal(city,street)` would select the `city` and
`street` values inside the `postal` object inside the `address` object
* `features`
Supports selecting arbitrary fields in features similar to `attributes` (see also features documentation for more details)
* `_namespace`
Specifically selects the namespace also contained in the `thingId`
* `_revision`
Specifically selects the revision of the thing. The revision is a counter, which is incremented on each modification of a thing.
* `_created`
Specifically selects the created timestamp of the thing in ISO-8601 UTC format. The timestamp is set on creation of a thing.
* `_modified`
Specifically selects the modified timestamp of the thing in ISO-8601 UTC format. The timestamp is set on each modification of a thing.
* `_metadata`
Specifically selects the Metadata of the thing. The content is a JSON object having the Thing's JSON structure with the difference that the JSON leaves of the Thing are JSON objects containing the metadata.
* `_policy`
Specifically selects the content of the policy associated to the thing. (By default, only the policyId is returned.)
#### Examples
* `?fields=thingId,attributes,features`
* `?fields=attributes(model,manufacturer),features`
required: false
schema:
type: string
ThingIdPathParam:
name: thingId
in: path
description: 'The ID of a thing needs to follow 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
schema:
type: string
TimeoutParam:
name: timeout
in: query
description: |-
Defines how long the backend should wait for completion of the request, e.g. applied when waiting for requested
acknowledgements via the `requested-acks` param. Can be specified without unit (then seconds are assumed) or
together with `s`, `ms` or `m` unit. Example: `42s`, `1m`.
The default (if omitted) timeout is `10s`. Maximum value: `60s`.
A value of `0` applies fire and forget semantics for the command resulting in setting `response-required=false`.
required: false
schema:
type: string
schemas:
Error:
properties:
status:
type: integer
description: The HTTP status of the error
message:
type: string
description: The message of the error - what went wrong
description:
type: string
description: A description how to fix the error or more details
href:
type: string
description: A link to further information about the error and how to fix it
required:
- status
- message
AdvancedError:
properties:
status:
type: integer
description: The HTTP status of the error
error:
type: string
description: The error code of the occurred exception
message:
type: string
description: The message of the error - what went wrong
description:
type: string
description: A description how to fix the error or more details
href:
type: string
description: A link to further information about the error and how to fix it
required:
- status
- error
- message
Attributes:
type: object
description: An arbitrary JSON object describing the attributes of a thing.
Definition:
type: string
description: 'A single fully qualified identifier of a definition in the form ''namespace:name:version'''
pattern: '([_a-zA-Z0-9\-.]+):([_a-zA-Z0-9\-.]+):([_a-zA-Z0-9\-.]+)'
FeatureDefinition:
type: array
description: The definitions of a feature.
items:
type: string
description: 'A single fully qualified identifier of a feature definition in the form ''namespace:name:version'''
pattern: '([_a-zA-Z0-9\-.]+):([_a-zA-Z0-9\-.]+):([_a-zA-Z0-9\-.]+)'
FeatureProperties:
type: object
description: An arbitrary JSON object describing the properties of a feature.
FeatureDesiredProperties:
type: object
description: An arbitrary JSON object describing the desired properties of a feature.
Feature:
type: object
properties:
definition:
$ref: '#/components/schemas/FeatureDefinition'
properties:
$ref: '#/components/schemas/FeatureProperties'
desiredProperties:
$ref: '#/components/schemas/FeatureDesiredProperties'
SearchResultThings:
properties:
items:
type: array
items:
$ref: '#/components/schemas/Thing'
cursor:
type: string
SearchResultThingsCount:
type: integer
NewThing:
type: object
properties:
_policy:
allOf:
- $ref: '#/components/schemas/Policy'
description: |-
The initial policy to create for this thing. This will create a separate policy entity managed by resource `/policies/{thingId}`.
Use the placeholder `{{ request:subjectId }}` in order to let the backend insert the authenticated subjectId of the HTTP request.
_copyPolicyFrom:
type: string
description: |-
This field may contain
* the policy ID of an existing policy.
The policy is copied and used for this newly created thing. The
caller needs to have READ and WRITE<sup>*</sup> access to the policy.
* a placeholder reference to a thing in the format {{ ref:things/[thingId]/policyId }} where you need to
replace [thingId] with a valid thing ID.
The newly created thing will then obtain a copy of the policy of
the referenced thing. The caller needs to have READ access to the thing and READ and WRITE<sup>*</sup>
access to the policy of the thing.
<sup>*</sup> The check for WRITE permission avoids locking yourself out of the newly created policy. You can
bypass this check by setting the header `allowPolicyLockout` to `true`. Be aware that the authorized
subject cannot modify the policy if you do not assign WRITE permission on the policy resource!
If you want to specify a policy ID for the copied policy, use the policyId field.
This field must not be used together with the field _policy. If you specify both _policy and _copyPolicyFrom
this will lead to an error response.
policyId:
type: string
description: |-
The policy ID used for controlling access to this thing. Managed by
resource `/policies/{policyId}`.
definition:
$ref: '#/components/schemas/Definition'
attributes:
$ref: '#/components/schemas/Attributes'
features:
$ref: '#/components/schemas/Features'
required:
- policyId
Thing:
type: object
properties:
thingId:
type: string
description: Unique identifier representing the thing
policyId:
type: string
description: 'The ID of the policy which controls the access to this thing. policies are managed by resource `/policies/{policyId}`'
definition:
$ref: '#/components/schemas/Definition'
attributes:
$ref: '#/components/schemas/Attributes'
features:
$ref: '#/components/schemas/Features'
_revision:
type: string
description: |-
_(read-only)_ The revision is a counter which is incremented on each modification of a Thing. This field
is not returned by default but must be selected explicitly.
_created:
type: string
description: |-
_(read-only)_ The created timestamp of the Thing in ISO-8601 UTC format. The timestamp is set on creation
of a Thing. This field is not returned by default but must be selected explicitly.
_modified:
type: string
description: |-
_(read-only)_ The modified timestamp of the Thing in ISO-8601 UTC format. The timestamp is set on each
modification of a Thing. This field is not returned by default but must be selected explicitly.
_metadata:
type: object
description: _(read-only)_ The Metadata of the Thing. This field is not returned by default but must be selected explicitly.
required:
- thingId
- policyId
NewPolicy:
type: object
description: Policy consisting of policy entries
properties:
entries:
$ref: '#/components/schemas/PolicyEntries'
required:
- entries
Policy:
type: object
description: Policy consisting of policy entries
properties:
policyId:
type: string
description: Unique identifier representing the policy
entries:
$ref: '#/components/schemas/PolicyEntries'
required:
- policyId
- entries
PolicyEntries:
type: object
description: Policy entries containing one policy entry for each arbitrary `label` key
properties:
label1:
$ref: '#/components/schemas/PolicyEntry'
labelN:
$ref: '#/components/schemas/PolicyEntry'
PolicyEntry:
type: object
description: Single policy entry containing Subjects and Resources.
properties:
subjects:
$ref: '#/components/schemas/Subjects'
resources:
$ref: '#/components/schemas/Resources'
required:
- subjects
- resources
Subjects:
type: object
description: A SubjectEntry defines who is addressed.
properties:
'nginx:subjectId1':
$ref: '#/components/schemas/SubjectEntry'
'nginx:subjectIdN':
$ref: '#/components/schemas/SubjectEntry'
SubjectEntry:
type: object
description: Single (Authorization) Subject entry holding its type.
required:
- type
properties:
type:
type: string
description: 'The type is offered only for documentation purposes. You are not restricted to any specific types, but we recommend to use it to specify the kind of the subject as shown in our examples.'
expiry:
type: string
description: The optional expiry timestamp (formatted in ISO-8601) indicates how long this subject should be considered active before it is automatically deleted from the Policy.
format: date-time
announcement:
$ref: '#/components/schemas/SubjectAnnouncement'
example:
type: 'This is some description for this subject, adjust as needed.'
expiry: '2020-12-07T11:36:40Z'
announcement:
beforeExpiry: 5m
whenDeleted: true
Resources:
type: object
description: |-
(Authorization) Resources containing one ResourceEntry for each
`type:path` key, `type` being one of the following `thing`, `policy`, `message`.
additionalProperties:
$ref: '#/components/schemas/ResourceEntry'
example:
'thing:/':
grant:
- READ
- WRITE
revoke: null
'thing:/attributes/some/path':
grant: null
revoke:
- READ
'policy:/':
grant:
- READ
- WRITE
revoke: null
'message:/':
grant:
- READ
- WRITE
revoke: null
ResourceEntry:
type: object
description: |-
Single (Authorization) Resource entry defining permissions per effect.
Allowed effects are `grant` and `revoke`.
properties:
grant:
type: array
items:
$ref: '#/components/schemas/Permission'
revoke:
type: array
items:
$ref: '#/components/schemas/Permission'
Permission:
type: string
description: A Permission allows a certain action on an entity
enum:
- READ
- WRITE
SubjectAnnouncement:
type: object
description: Settings for announcements to be made about the subject.
properties:
beforeExpiry:
type: string
description: |-
The duration before expiry when an announcement should be made.
Must be a positive integer followed by one of `h` (hour), `m` (minute) or `s` (second).
whenDeleted:
type: boolean
description: Whether an announcement should be made when this subject is deleted.
example:
beforeExpiry: 5m
whenDeleted: true
Features:
type: object
description: |-
List of features where the key represents the `featureId` of each feature.
The `featureId` key must be unique in the list.
additionalProperties:
$ref: '#/components/schemas/Feature'
WhoAmI:
type: object
description: Contains information about the current user and the auth subjects available for the used authentication.
properties:
defaultSubject:
$ref: '#/components/schemas/WhoAmISubject'
subjects:
type: array
items:
$ref: '#/components/schemas/WhoAmISubject'
WhoAmISubject:
type: string
description: An auth subject that can be used to provide access for a caller (e.g. in subject entries of policies).
securitySchemes:
NginxBasic:
type: http
description: Eclipse Ditto sandbox demo user (demo1 ... demo9) + password (demo)
scheme: basic
Bearer:
type: http
scheme: bearer
bearerFormat: JWT
description: A JSON Web Token issued by a supported OAuth 2.0 Identity Provider.
Google:
type: oauth2
description: Allow Eclipse Ditto to perform OAuth2.0 based authentication accessing your Google-ID.
x-tokenName: id_token
flows:
authorizationCode:
authorizationUrl: 'https://accounts.google.com/o/oauth2/v2/auth'
tokenUrl: /oauth2/google/token
scopes:
openid: Access your Google-ID