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