| openapi: 3.0.0 |
| info: |
| title: Eclipse Ditto™ HTTP API - Deprecated |
| version: '1' |
| 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/1' |
| description: online Ditto Sandbox |
| - url: /api/1 |
| description: local Ditto |
| tags: |
| - name: Things |
| description: Manage every Thing |
| - name: Features |
| description: Structure the Features of your Things |
| - name: Things-Search |
| description: Find every Thing |
| - name: Messages |
| description: Talk with your Things |
| security: |
| - Google: |
| - openid |
| - NginxBasic: [] |
| - Bearer: [] |
| paths: |
| /things: |
| get: |
| summary: List all available Things |
| description: |- |
| Returns all Things passed in by the required parameter `ids`. |
| |
| Optionally you can use field selectors (see parameter `fields`) to only get the specified fields. |
| |
| To retrieve all Things the logged in user is allowed to read, please use the `GET /search/things` operation. |
| deprecated: true |
| 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' |
| 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 the Thing defined in the optional JSON body. |
| |
| The ID of the created Thing is a UUID generated by the service with the default namespace `org.eclipse.ditto`. |
| Any `thingId` |
| specified in the request body is therefore ignored. The ACL of the created Thing must include at least one |
| entry with `READ`, `WRITE` and `ADMINISTRATE` permissions set to `true`. |
| If no ACL is provided, a default ACL with an entry for the authorized subject with all permissions set to |
| `true` will be created. |
| |
| |
| 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. |
| deprecated: true |
| tags: |
| - Things |
| 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. The JSON of the Thing to be created was invalid or the `thingId` was |
| wrongly set in the request body. |
| 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' |
| '412': |
| $ref: '#/components/responses/preconditionFailed' |
| '413': |
| $ref: '#/components/responses/entityTooLarge' |
| requestBody: |
| content: |
| application/json: |
| schema: |
| $ref: '#/components/schemas/NewThing' |
| description: |- |
| JSON representation of the Thing to be created. |
| |
| |
| Use the placeholder `{{ request:subjectId }}` in order to let the backend insert the authenticated subjectId of the HTTP request. |
| '/things/{thingId}': |
| get: |
| summary: Retrieve a specific Thing |
| description: |- |
| Returns the Thing identified by the `thingId` path parameter. |
| The response includes all details about the Thing. |
| Optionally you can use field selectors (see parameter `fields`) to only get the specified fields. |
| deprecated: true |
| tags: |
| - Things |
| parameters: |
| - $ref: '#/components/parameters/thingIdPathParam' |
| - $ref: '#/components/parameters/thingFieldsQueryParam' |
| - $ref: '#/components/parameters/ifMatchHeaderParam' |
| - $ref: '#/components/parameters/ifNoneMatchHeaderParam' |
| 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. Either 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)) |
| or 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' |
| '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. The `thingId` has to |
| conform to the [namespaced entity ID notation](https://www.eclipse.org/ditto/basic-namespaces-and-names.html#namespaced-id). |
| |
| #### Valid examples |
| |
| * `org.eclipse.ditto.myproject:myFridge1` |
| * `mynamespace:myFridge1` |
| |
| #### Invalid examples |
| |
| * `42:myFridge1` |
| * `.foo:myFridge1` |
| * `bar.:myFridge1` |
| |
| The ID of a Thing can't be changed after creation. Any `thingId` specified in the request body is therefore ignored. |
| |
| ### Creation of a new Thing |
| |
| The ACL of the created Thing must include at least one entry with `READ`, `WRITE` and `ADMINISTRATE` permissions set to `true`. |
| If no ACL is provided, a default ACL with an entry for the authorized subject with all permissions set to `true` will be created. |
| |
| |
| Use the placeholder `{{ request:subjectId }}` in order to let the backend insert the authenticated subjectId of the HTTP request. |
| |
| |
| 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. |
| |
| ### Permissions for updating an existing Thing |
| |
| For updating an existing Thing the authorized subject has to have the `WRITE` permission. |
| If the new Thing to update contains an `acl` entry, the authorized subject additionally has to have the `ADMINISTRATE` permission. |
| For authorized subjects which don't have the `ADMINISTRATE` permission, the complete Thing may be updated if the `acl` entry is not set. |
| |
| ### Partially updating an existing Thing |
| |
| When updating an existing Thing already containing `attributes`, `acl` or `features` the already 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. |
| |
| |
| For example: A Thing already exists with this content: |
| |
| ``` |
| |
| { |
| "thingId": "namespace:thing-name", |
| "acl": {...}, |
| "attributes": { |
| "foo": 1 |
| }, |
| "features": {...} |
| } |
| |
| ``` |
| |
| The Thing's `attributes` may be modified without having to pass the `acl` or the `features` in again. The content |
| of the request's body would be sufficient for updating the `attributes`: |
| |
| ``` |
| |
| { |
| "attributes": { |
| "foo": 2, |
| "bar": false |
| } |
| } |
| |
| ``` |
| |
| The `acl` and `features` of the Thing will not be overwritten, the Thing will be merged as one would expect it: |
| |
| ``` |
| |
| { |
| "thingId": "namespace:thing-name", |
| "acl": {...}, |
| "attributes": { |
| "foo": 2, |
| "bar": false |
| }, |
| "features": {...} |
| } |
| |
| ``` |
| deprecated: true |
| tags: |
| - Things |
| parameters: |
| - $ref: '#/components/parameters/thingIdPathParam' |
| - $ref: '#/components/parameters/ifMatchHeaderParam' |
| - $ref: '#/components/parameters/ifNoneMatchHeaderParam' |
| 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. Either 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)) |
| or the JSON of the Thing to be created/modified was either invalid or did contain a `thingId` which did not match the ID in the URL. |
| 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 as the caller had insufficient permissions. |
| For modifying an existing Thing `WRITE` permission is required. |
| |
| If the `acl` of the Thing should be updated as well, the permission `ADMINISTRATE` is additionally required. |
| The complete Thing without `acl` can however be updated with `WRITE` permission if the body does not contain an `acl` entry. |
| 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' |
| description: |- |
| JSON representation of the Thing to be modified. |
| |
| |
| Use the placeholder `{{ request:subjectId }}` in order to let the backend insert the authenticated subjectId of the HTTP request. |
| delete: |
| summary: Delete a specific Thing |
| description: Deletes the Thing identified by the `thingId` path parameter. |
| deprecated: true |
| tags: |
| - Things |
| parameters: |
| - $ref: '#/components/parameters/thingIdPathParam' |
| - $ref: '#/components/parameters/ifMatchHeaderParam' |
| - $ref: '#/components/parameters/ifNoneMatchHeaderParam' |
| responses: |
| '204': |
| description: The Thing 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 as the caller had insufficient permissions. |
| For deleting an existing Thing `WRITE` and `ADMINISTRATE` permissions are 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' |
| '/things/{thingId}/acl': |
| get: |
| summary: Retrieve the complete ACL of a Thing |
| description: |- |
| Returns the Access Control List (ACL) of the Thing identified by the `thingId` path parameter. |
| The response contains the ACL as JSON object containing a key for each subject having ACL permissions. |
| deprecated: true |
| tags: |
| - Things |
| parameters: |
| - $ref: '#/components/parameters/thingIdPathParam' |
| - $ref: '#/components/parameters/ifMatchHeaderParamHash' |
| - $ref: '#/components/parameters/ifNoneMatchHeaderParam' |
| responses: |
| '200': |
| description: The request successfully returned completed and returned is the Access Control List. |
| 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/Acl' |
| example: |
| authorizationSubject1: |
| READ: true |
| WRITE: true |
| ADMINISTRATE: true |
| authorizationSubjectN: |
| READ: true |
| WRITE: true |
| ADMINISTRATE: true |
| '304': |
| $ref: '#/components/responses/notModified' |
| '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' |
| '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: Modify the complete ACL of a Thing |
| description: |- |
| Modify the complete Access Control List (ACL) of the Thing identified by the `thingId` path parameter. |
| |
| The ACL must include at least one entry with `READ`, `WRITE` and `ADMINISTRATE` permissions set to `true`. |
| deprecated: true |
| tags: |
| - Things |
| parameters: |
| - $ref: '#/components/parameters/thingIdPathParam' |
| - $ref: '#/components/parameters/ifMatchHeaderParamHash' |
| - $ref: '#/components/parameters/ifNoneMatchHeaderParam' |
| responses: |
| '204': |
| description: The Access Control List 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. Either 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)) |
| or the JSON was invalid, or no valid ACL 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 as the caller had insufficient permissions. |
| For modifying the ACL of an existing Thing `ADMINISTRATE` 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 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/Acl' |
| example: |
| '{{ request:subjectId }}': |
| READ: true |
| WRITE: true |
| ADMINISTRATE: true |
| description: |- |
| JSON representation of the Access Control List (ACL). |
| |
| |
| Use the placeholder `{{ request:subjectId }}` in order to let the backend insert the authenticated subjectId of the HTTP request. |
| required: true |
| '/things/{thingId}/acl/{authorizationSubject}': |
| get: |
| summary: Retrieve one ACL entry of a Thing for a specific subject |
| description: |- |
| Returns one Access Control List (ACL) entry of the Thing identified by the `thingId` path parameter and for the subject |
| identified by the `authorizationSubject` path parameter. |
| deprecated: true |
| tags: |
| - Things |
| parameters: |
| - $ref: '#/components/parameters/thingIdPathParam' |
| - $ref: '#/components/parameters/authorizationSubjectPathParam' |
| - $ref: '#/components/parameters/ifMatchHeaderParamHash' |
| - $ref: '#/components/parameters/ifNoneMatchHeaderParam' |
| responses: |
| '200': |
| description: The request successfully returned completed and returned is the ACL 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/AclEntry' |
| '304': |
| $ref: '#/components/responses/notModified' |
| '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' |
| '404': |
| description: The request could not be completed. The Thing with the given ID or the ACL 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 one ACL entry of a Thing for a specific subject |
| description: |- |
| Create or modify the Access Control List (ACL) entry of the Thing identified by the `thingId` path parameter and for the subject |
| identified by the `authorizationSubject` path parameter. |
| |
| An ACL entry must contain values for `READ`, `WRITE` and `ADMINISTRATE` permissions, all other permissions will be ignored. |
| The ACL must contain at least one entry with all permissions set to `true`. |
| deprecated: true |
| tags: |
| - Things |
| parameters: |
| - $ref: '#/components/parameters/thingIdPathParam' |
| - $ref: '#/components/parameters/authorizationSubjectPathParam' |
| - $ref: '#/components/parameters/ifMatchHeaderParamHash' |
| - $ref: '#/components/parameters/ifNoneMatchHeaderParam' |
| responses: |
| '201': |
| description: The ACL 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 ACL entry |
| schema: |
| type: string |
| content: |
| application/json: |
| schema: |
| $ref: '#/components/schemas/AclEntry' |
| '204': |
| description: The ACL 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. Either 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)) |
| or the JSON was invalid, or no valid ACL 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 as the caller had insufficient permissions. |
| For modifying an ACL entry of an existing Thing `ADMINISTRATE` 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 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: |
| $ref: '#/components/requestBodies/AclEntry' |
| delete: |
| summary: Delete one ACL entry of a Thing for a specific subject |
| description: |- |
| Deletes the the Access Control List (ACL) entry of the Thing identified by the `thingId` path parameter and for the subject |
| identified by the `authorizationSubject` path parameter. |
| |
| The ACL must contain at least one entry with all permissions set to `true`. |
| deprecated: true |
| tags: |
| - Things |
| parameters: |
| - $ref: '#/components/parameters/thingIdPathParam' |
| - $ref: '#/components/parameters/authorizationSubjectPathParam' |
| - $ref: '#/components/parameters/ifMatchHeaderParamHash' |
| - $ref: '#/components/parameters/ifNoneMatchHeaderParam' |
| responses: |
| '204': |
| description: The ACL entry 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 as the caller had insufficient permissions. |
| For deleting an ACL entry of an existing Thing `ADMINISTRATE` 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 in the context of the authenticated user. |
| content: |
| application/json: |
| schema: |
| $ref: '#/components/schemas/AdvancedError' |
| '412': |
| $ref: '#/components/responses/preconditionFailed' |
| '/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. |
| deprecated: true |
| tags: |
| - Things |
| parameters: |
| - $ref: '#/components/parameters/thingIdPathParam' |
| - $ref: '#/components/parameters/attributesFieldsQueryParam' |
| - $ref: '#/components/parameters/ifMatchHeaderParamHash' |
| - $ref: '#/components/parameters/ifNoneMatchHeaderParam' |
| 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. 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 at once. |
| The Attributes will be replaced by the request body's JSON. |
| deprecated: true |
| tags: |
| - Things |
| parameters: |
| - $ref: '#/components/parameters/thingIdPathParam' |
| - $ref: '#/components/parameters/ifMatchHeaderParamHash' |
| - $ref: '#/components/parameters/ifNoneMatchHeaderParam' |
| 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. Either 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)) |
| or the JSON was invalid or 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 as the caller had 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 at once. |
| deprecated: true |
| tags: |
| - Things |
| parameters: |
| - $ref: '#/components/parameters/thingIdPathParam' |
| - $ref: '#/components/parameters/ifMatchHeaderParamHash' |
| - $ref: '#/components/parameters/ifNoneMatchHeaderParam' |
| responses: |
| '204': |
| description: The Attributes were 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 as the caller had 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), e.g.: |
| `/things/{thingId}/attributes/address/city` in order to retrieve the `city` field of an `address` object. |
| deprecated: true |
| tags: |
| - Things |
| parameters: |
| - $ref: '#/components/parameters/thingIdPathParam' |
| - $ref: '#/components/parameters/attributePathPathParam' |
| - $ref: '#/components/parameters/ifMatchHeaderParamHash' |
| - $ref: '#/components/parameters/ifNoneMatchHeaderParam' |
| 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. 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. |
| The Attribute will be created if it doesn't exist or else updated. The Attribute (JSON) can be referenced hierarchically by applying JSON Pointer notation (RFC-6901), e.g.: |
| `/things/{thingId}/attributes/address/city` in order to create/update the `city` field of an `address` object. |
| deprecated: true |
| tags: |
| - Things |
| parameters: |
| - $ref: '#/components/parameters/thingIdPathParam' |
| - $ref: '#/components/parameters/attributePathPathParam' |
| - $ref: '#/components/parameters/ifMatchHeaderParamHash' |
| - $ref: '#/components/parameters/ifNoneMatchHeaderParam' |
| 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. 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 as the caller had insufficient permissions. For modifying 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 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), e.g.: |
| `/things/{thingId}/attributes/address/city` in order to delete the `city` field of an `address` object. |
| deprecated: true |
| tags: |
| - Things |
| parameters: |
| - $ref: '#/components/parameters/thingIdPathParam' |
| - $ref: '#/components/parameters/attributePathPathParam' |
| - $ref: '#/components/parameters/ifMatchHeaderParamHash' |
| - $ref: '#/components/parameters/ifNoneMatchHeaderParam' |
| responses: |
| '204': |
| description: The Attribute 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 as the caller had 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. |
| deprecated: true |
| tags: |
| - Features |
| parameters: |
| - $ref: '#/components/parameters/thingIdPathParam' |
| - $ref: '#/components/parameters/featuresFieldsQueryParam' |
| - $ref: '#/components/parameters/ifMatchHeaderParamHash' |
| - $ref: '#/components/parameters/ifNoneMatchHeaderParam' |
| 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. Either 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)) |
| or 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' |
| '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 the Features of a Thing identified by the `thingId` path parameter at once. The list of Features will be replaced by the request body's JSON. |
| deprecated: true |
| tags: |
| - Features |
| parameters: |
| - $ref: '#/components/parameters/thingIdPathParam' |
| - $ref: '#/components/parameters/ifMatchHeaderParamHash' |
| - $ref: '#/components/parameters/ifNoneMatchHeaderParam' |
| 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. Either 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)) |
| or the JSON was invalid or 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 as the caller had 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' |
| description: 'JSON object of the Features to be modified at once. It can be also `null` or an empty object `{}` (all features cleared).' |
| required: true |
| delete: |
| summary: Delete all Features of a specific Thing |
| description: Deletes all features of the Thing identified by the `thingId` path parameter. |
| deprecated: true |
| tags: |
| - Features |
| parameters: |
| - $ref: '#/components/parameters/thingIdPathParam' |
| - $ref: '#/components/parameters/ifMatchHeaderParamHash' |
| - $ref: '#/components/parameters/ifNoneMatchHeaderParam' |
| responses: |
| '204': |
| description: The Features were 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 as the caller had 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. |
| deprecated: true |
| tags: |
| - Features |
| parameters: |
| - $ref: '#/components/parameters/thingIdPathParam' |
| - $ref: '#/components/parameters/featureIdPathPathParam' |
| - $ref: '#/components/parameters/featureFieldsQueryParam' |
| - $ref: '#/components/parameters/ifMatchHeaderParamHash' |
| - $ref: '#/components/parameters/ifNoneMatchHeaderParam' |
| 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. Either 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)) |
| or 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' |
| '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. |
| deprecated: true |
| tags: |
| - Features |
| parameters: |
| - $ref: '#/components/parameters/thingIdPathParam' |
| - $ref: '#/components/parameters/featureIdPathPathParam' |
| - $ref: '#/components/parameters/ifMatchHeaderParamHash' |
| - $ref: '#/components/parameters/ifNoneMatchHeaderParam' |
| 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. Either 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)) |
| or the JSON of the Feature to be created 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' |
| '403': |
| description: |- |
| The request could not be completed as the caller had 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' |
| description: 'JSON representation of the Feature to be created/modified. It can also be `null` or an empty object `{}`.' |
| 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. |
| deprecated: true |
| tags: |
| - Features |
| parameters: |
| - $ref: '#/components/parameters/thingIdPathParam' |
| - $ref: '#/components/parameters/featureIdPathPathParam' |
| - $ref: '#/components/parameters/ifMatchHeaderParamHash' |
| - $ref: '#/components/parameters/ifNoneMatchHeaderParam' |
| responses: |
| '204': |
| description: The Feature 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 as the caller had 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 of the Feature identified by the `thingId` and |
| `featureId` path parameter. |
| deprecated: true |
| tags: |
| - Features |
| parameters: |
| - $ref: '#/components/parameters/thingIdPathParam' |
| - $ref: '#/components/parameters/featureIdPathPathParam' |
| - $ref: '#/components/parameters/ifMatchHeaderParamHash' |
| - $ref: '#/components/parameters/ifNoneMatchHeaderParam' |
| 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. Either 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)) |
| or 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' |
| '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 at once. The Definition will be replaced |
| by the request body's JSON array. |
| deprecated: true |
| tags: |
| - Features |
| parameters: |
| - $ref: '#/components/parameters/thingIdPathParam' |
| - $ref: '#/components/parameters/featureIdPathPathParam' |
| - $ref: '#/components/parameters/ifMatchHeaderParamHash' |
| - $ref: '#/components/parameters/ifNoneMatchHeaderParam' |
| 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. Either 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)) |
| or the JSON 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' |
| '403': |
| description: |- |
| The request could not be completed as the caller had 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' |
| 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. |
| deprecated: true |
| tags: |
| - Features |
| parameters: |
| - $ref: '#/components/parameters/thingIdPathParam' |
| - $ref: '#/components/parameters/featureIdPathPathParam' |
| - $ref: '#/components/parameters/ifMatchHeaderParamHash' |
| - $ref: '#/components/parameters/ifNoneMatchHeaderParam' |
| 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 as the caller had 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. |
| deprecated: true |
| tags: |
| - Features |
| parameters: |
| - $ref: '#/components/parameters/thingIdPathParam' |
| - $ref: '#/components/parameters/featureIdPathPathParam' |
| - $ref: '#/components/parameters/propertiesFieldsQueryParam' |
| - $ref: '#/components/parameters/ifMatchHeaderParamHash' |
| - $ref: '#/components/parameters/ifNoneMatchHeaderParam' |
| 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. Either 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)) |
| or 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' |
| '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 at once. |
| The Properties will be replaced by the request body's JSON. |
| deprecated: true |
| tags: |
| - Features |
| parameters: |
| - $ref: '#/components/parameters/thingIdPathParam' |
| - $ref: '#/components/parameters/featureIdPathPathParam' |
| - $ref: '#/components/parameters/ifMatchHeaderParamHash' |
| - $ref: '#/components/parameters/ifNoneMatchHeaderParam' |
| 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. Either 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)) |
| or the JSON 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' |
| '403': |
| description: |- |
| The request could not be completed as the caller had 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' |
| 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. |
| deprecated: true |
| tags: |
| - Features |
| parameters: |
| - $ref: '#/components/parameters/thingIdPathParam' |
| - $ref: '#/components/parameters/featureIdPathPathParam' |
| - $ref: '#/components/parameters/ifMatchHeaderParamHash' |
| - $ref: '#/components/parameters/ifNoneMatchHeaderParam' |
| responses: |
| '204': |
| description: The Properties were 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 as the caller had 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 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), e.g.: |
| `/things/{thingId}/features/{featureId}/properties/location/latitude` in order to retrieve the `latitude` field of an `location` Property. |
| deprecated: true |
| tags: |
| - Features |
| parameters: |
| - $ref: '#/components/parameters/thingIdPathParam' |
| - $ref: '#/components/parameters/featureIdPathPathParam' |
| - $ref: '#/components/parameters/propertyPathPathParam' |
| - $ref: '#/components/parameters/ifMatchHeaderParamHash' |
| - $ref: '#/components/parameters/ifNoneMatchHeaderParam' |
| 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. 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), e.g.: |
| `/things/{thingId}/features/{featureId}/properties/location/latitude` in order to create/update the `latitude` field of an `location` object. |
| deprecated: true |
| tags: |
| - Features |
| parameters: |
| - $ref: '#/components/parameters/thingIdPathParam' |
| - $ref: '#/components/parameters/featureIdPathPathParam' |
| - $ref: '#/components/parameters/propertyPathPathParam' |
| - $ref: '#/components/parameters/ifMatchHeaderParamHash' |
| - $ref: '#/components/parameters/ifNoneMatchHeaderParam' |
| 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. Either 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)) |
| or the JSON 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' |
| '403': |
| description: |- |
| The request could not be completed as the caller had 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), e.g.: |
| `/things/{thingId}/features/{featureId}/properties/location/latitude` in order to delete the `latitude` field of an `location` Property. |
| deprecated: true |
| tags: |
| - Features |
| parameters: |
| - $ref: '#/components/parameters/thingIdPathParam' |
| - $ref: '#/components/parameters/featureIdPathPathParam' |
| - $ref: '#/components/parameters/propertyPathPathParam' |
| - $ref: '#/components/parameters/ifMatchHeaderParamHash' |
| - $ref: '#/components/parameters/ifNoneMatchHeaderParam' |
| responses: |
| '204': |
| description: The Property 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' |
| '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}/inbox/claim': |
| post: |
| summary: Initiates claiming a specific Thing in order to gain access. |
| description: |- |
| 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 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. |
| No special permissions are required to issue a Claim message. |
| |
| 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). |
| deprecated: true |
| tags: |
| - Messages |
| parameters: |
| - $ref: '#/components/parameters/thingIdPathParam' |
| - $ref: '#/components/parameters/messageClaimTimeoutParam' |
| 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. Either 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)) |
| or at least one of the defined path 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' |
| '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' |
| '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: |- |
| Send a message with the subject `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 |
| API does not provide any kind of acknowledgement that the message was |
| received by the Thing. In order to send a message, the user needs `WRITE` |
| permission at the Thing level. |
| |
| The HTTP request 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). |
| deprecated: true |
| tags: |
| - Messages |
| parameters: |
| - $ref: '#/components/parameters/thingIdPathParam' |
| - $ref: '#/components/parameters/messageSubjectPathParam' |
| - $ref: '#/components/parameters/messageTimeoutParam' |
| responses: |
| '202': |
| description: The message was sent but not necessarly received by the Thing (fire and forget). |
| '400': |
| description: |- |
| The request could not be completed. Either 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)) |
| or at least one of the defined path 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' |
| '403': |
| description: The request could not be completed as the caller does not have `WRITE` permission at the Thing level. |
| 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. |
| In order to send a message, the user needs `WRITE` permission at the |
| Thing level. |
| |
| The HTTP request 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). |
| deprecated: true |
| tags: |
| - Messages |
| parameters: |
| - $ref: '#/components/parameters/thingIdPathParam' |
| - $ref: '#/components/parameters/messageSubjectPathParam' |
| - $ref: '#/components/parameters/messageTimeoutParam' |
| responses: |
| '202': |
| description: The message was sent (fire and forget). |
| '400': |
| description: |- |
| The request could not be completed. Either 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)) |
| or at least one of the defined path 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' |
| '403': |
| description: The request could not be completed as the caller does not have `WRITE` permission at the Thing level. |
| 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 API does not provide any kind of acknowledgement that the |
| message was received by the Feature. In order to send a message, the user needs `WRITE` permission at the Thing level. |
| |
| The HTTP request 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). |
| deprecated: true |
| tags: |
| - Messages |
| parameters: |
| - $ref: '#/components/parameters/thingIdPathParam' |
| - $ref: '#/components/parameters/featureIdPathPathParam' |
| - $ref: '#/components/parameters/messageSubjectPathParam' |
| - $ref: '#/components/parameters/messageTimeoutParam' |
| responses: |
| '202': |
| description: The message was sent but not necessarly received by the Feature (fire and forget). |
| '400': |
| description: |- |
| The request could not be completed. Either 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)) |
| or at least one of the defined path 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' |
| '403': |
| description: The request could not be completed as the caller does not have `WRITE` permission at the Thing level. |
| 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. In order to send a message, the user needs `WRITE` permission |
| at the Thing level. |
| |
| The HTTP request 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). |
| deprecated: true |
| tags: |
| - Messages |
| parameters: |
| - $ref: '#/components/parameters/thingIdPathParam' |
| - $ref: '#/components/parameters/featureIdPathPathParam' |
| - $ref: '#/components/parameters/messageSubjectPathParam' |
| - $ref: '#/components/parameters/messageTimeoutParam' |
| responses: |
| '202': |
| description: The message was sent (fire and forget). |
| '400': |
| description: |- |
| The request could not be completed. Either 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)) |
| or at least one of the defined path 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' |
| '403': |
| description: The request could not be completed as the caller does not have `WRITE` permission at the Thing level. |
| 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' |
| /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 there are returned all things which the logged |
| in user is allowed to read. The resource supports sorting |
| and paging. If paging is not explicitly specified by means of the `limit` |
| option, a default count of `25` documents is returned. |
| |
| 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")``` |
| deprecated: true |
| parameters: |
| - $ref: '#/components/parameters/searchFilter' |
| - $ref: '#/components/parameters/namespacesFilter' |
| - $ref: '#/components/parameters/thingFieldsQueryParam' |
| - 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`. |
| * ```cursor({cursor-id})``` Start the search from the cursor location. Specify the cursor ID without |
| quotation marks. Cursor IDs are given in responses and mark the position after the final search result. |
| 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, time-outs 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 combine 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 was 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")``` |
| deprecated: true |
| parameters: |
| - $ref: '#/components/parameters/searchFilter' |
| - $ref: '#/components/parameters/namespacesFilter' |
| tags: |
| - Things-Search |
| responses: |
| '200': |
| description: A number indicating the amount of matched things |
| content: |
| application/json: |
| schema: |
| $ref: '#/components/schemas/SearchResultThingsCount' |
| '400': |
| description: The request could not be completed. A provided parameter was 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' |
| components: |
| requestBodies: |
| Attributes: |
| content: |
| application/json: |
| schema: |
| $ref: '#/components/schemas/Attributes' |
| 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 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\-]* |
| * an empty object: `{}` |
| required: true |
| AclEntry: |
| content: |
| application/json: |
| schema: |
| $ref: '#/components/schemas/AclEntry' |
| example: |
| READ: true |
| WRITE: true |
| ADMINISTRATE: true |
| description: |- |
| JSON representation of the Access Control List (ACL) entry for a single |
| authorization subject |
| required: true |
| 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 |
| 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 |
| 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 |
| 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: 'Attributes of a Thing: an arbitrary JSON object.' |
| FeatureDefinition: |
| type: array |
| items: |
| $ref: '#/components/schemas/FeatureDefinitionString' |
| FeatureDefinitionString: |
| 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: 'Properties of a Feature: an arbitrary JSON object.' |
| Feature: |
| type: object |
| properties: |
| definition: |
| $ref: '#/components/schemas/FeatureDefinition' |
| properties: |
| $ref: '#/components/schemas/FeatureProperties' |
| SearchResultThings: |
| properties: |
| items: |
| type: array |
| items: |
| $ref: '#/components/schemas/Thing' |
| cursor: |
| type: string |
| SearchResultThingsCount: |
| type: integer |
| NewThing: |
| type: object |
| properties: |
| acl: |
| $ref: '#/components/schemas/Acl' |
| attributes: |
| $ref: '#/components/schemas/Attributes' |
| features: |
| $ref: '#/components/schemas/Features' |
| Thing: |
| type: object |
| required: |
| - thingId |
| - acl |
| - attributes |
| - features |
| properties: |
| thingId: |
| type: string |
| description: |- |
| Unique identifier representing the Thing, has 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)). |
| acl: |
| $ref: '#/components/schemas/Acl' |
| 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. |
| Acl: |
| type: object |
| description: Access Control List containing one AclEntry for each arbitrary `authorizationSubject` key |
| additionalProperties: |
| $ref: '#/components/schemas/AclEntry' |
| AclEntry: |
| type: object |
| description: 'Single Access Control List entry containing the permissions (READ, WRITE, ADMINISTRATE) for the Authorization Subject.' |
| required: |
| - READ |
| - WRITE |
| - ADMINISTRATE |
| properties: |
| READ: |
| type: boolean |
| description: Whether the Authorization Subject has permissions to read this entity |
| WRITE: |
| type: boolean |
| description: Whether the Authorization Subject has permissions to modify this entity |
| ADMINISTRATE: |
| type: boolean |
| description: Whether the Authorization Subject has permissions to modify this entity's Access Control List |
| 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' |
| 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' |
| 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' |
| 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' |
| 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, when 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: |
| 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 |
| 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 HTTP 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 |
| 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 |
| featureIdPathPathParam: |
| name: featureId |
| in: path |
| description: The ID of the Feature - has to conform to RFC-3986 (URI) |
| required: true |
| schema: |
| type: string |
| attributePathPathParam: |
| name: attributePath |
| in: path |
| description: The path to the Attribute |
| required: true |
| schema: |
| type: string |
| thingIdPathParam: |
| name: thingId |
| in: path |
| description: |- |
| The ID of the Thing has 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 |
| schema: |
| type: string |
| messageSubjectPathParam: |
| name: messageSubject |
| in: path |
| description: The subject of the Message - has to conform to RFC-3986 (URI) |
| required: true |
| 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 |
| 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 |
| authorizationSubjectPathParam: |
| name: authorizationSubject |
| in: path |
| description: The subject for authorization (e.g. a user id) inside an ACL |
| required: true |
| schema: |
| type: string |
| propertyPathPathParam: |
| name: propertyPath |
| in: path |
| description: The path to the Property |
| 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` |
| |
| * `acl` |
| |
| * `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/make` would select only `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=attributes(model,make)` would select only `model` and `make` attribute values (if present) |
| * `?fields=attributes(location/longitude)` would select the `longitude` value inside the `location` 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. |
| |
| #### Examples |
| |
| * `?fields=thingId,attributes,features` |
| |
| * `?fields=attributes(model,make),features` |
| |
| * `?fields=thingId,attributes/location/longitude,attributes/address(city,street)` |
| required: false |
| 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 only `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 |
| 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 |
| 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 |
| 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 |
| searchFilter: |
| name: filter |
| in: query |
| description: |- |
| Possible values for the parameter: |
| |
| ##### Filter operations |
| |
| * ```eq({property},{value})``` |
| |
| * ```ne({property},{value})``` |
| |
| * ```gt({property},{value})``` |
| |
| * ```ge({property},{value})``` |
| |
| * ```lt({property},{value})``` |
| |
| * ```le({property},{value})``` |
| |
| * ```in({property},{value},{value},...)``` |
| |
| * ```like({property},{value})``` |
| |
| * ```exists({property})``` |
| |
| |
| 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 have the `owner` attribute. |
| |
| |
| ##### logical operations |
| |
| * ```and({query},{query},...)``` |
| |
| * ```or({query},{query},...)``` |
| |
| * ```not({query})``` |
| |
| |
| ##### Examples |
| |
| * ```eq(attributes/location,"kitchen")``` |
| |
| * ```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"))``` |
| required: false |
| schema: |
| type: string |
| 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. When this parameter is omitted, all namespaces will be queried. |
| |
| |
| #### Examples: |
| |
| * `?namespaces=com.example.namespace` |
| |
| * `?namespaces=com.example.namespace1,com.example.namespace2` |
| required: false |
| schema: |
| type: string |