| # Copyright (c) 2017 Contributors to the Eclipse Foundation |
| # |
| # See the NOTICE file(s) distributed with this work for additional |
| # information regarding copyright ownership. |
| # |
| # This program and the accompanying materials are made available under the |
| # terms of the Eclipse Public License 2.0 which is available at |
| # http://www.eclipse.org/legal/epl-2.0 |
| # |
| # SPDX-License-Identifier: EPL-2.0 |
| openapi: 3.0.0 |
| info: |
| title: Eclipse Ditto HTTP API - Deprecated |
| description: JSON-based, REST-like API for Eclipse Ditto |
| version: "1" |
| servers: |
| - url: https://ditto.eclipse.org/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 |
| - basicAuth: [] |
| - bearerAuth: [] |
| 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, sorted by their `thingId`. |
| 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. |
| 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' |
| example: {} |
| 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. |
| |
| ### 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' |
| example: {} |
| 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' |
| example: {} |
| 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' |
| example: {} |
| 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' |
| example: {} |
| 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' |
| example: {} |
| 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. |
| 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' |
| '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' |
| 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. |
| 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' |
| '413': |
| $ref: '#/components/responses/messageTooLarge' |
| 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. |
| 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' |
| '413': |
| $ref: '#/components/responses/messageTooLarge' |
| 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. |
| 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' |
| '413': |
| $ref: '#/components/responses/messageTooLarge' |
| 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. |
| 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' |
| '413': |
| $ref: '#/components/responses/messageTooLarge' |
| 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' |
| example: {} |
| 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 |
| example: {} |
| description: |- |
| JSON representation of the value to be created/updated. This may be as |
| well `null` or an empty object. |
| |
| Consider that the value has to be a JSON value, examples: |
| |
| * for a number, the JSON value is the number: `42` |
| |
| * for a string, the JSON value must be quoted: `"aString"` |
| |
| * for a boolean, the JSON value is the boolean: `true` |
| |
| * for an object, the JSON value is the object: `{ "key": "value"}` -} We strongly recommend to use a restricted set of characters for the key (identifier). Currently these identifiers should follow the pattern: [_a-zA-Z][_a-zA-Z0-9\-]* |
| |
| * for an list, the JSON value is the list: `[ 1,2,3 ]` |
| required: true |
| securitySchemes: |
| basicAuth: |
| type: http |
| description: |- |
| Eclipse Ditto sandbox demo user (demo1 ... demo9) + password (demo) |
| scheme: basic |
| bearerAuth: |
| type: http |
| scheme: bearer |
| bearerFormat: JWT |
| description: |- |
| A JSON Web Token issued by a supported OAuth 2.0 Identity Provider, e.g. a Google "id_token" |
| 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' |
| 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' |
| 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. |
| |
| * `_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")``` |
| |
| * ```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 |