| # Copyright (c) 2020 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 |
| get: |
| summary: List all features of a specific thing |
| description: |- |
| Returns all features of the thing identified by the `thingId` path parameter. |
| tags: |
| - Features |
| parameters: |
| - $ref: '../../parameters/thingIdPathParam.yml' |
| - $ref: '../../parameters/featuresFieldsQueryParam.yml' |
| - $ref: '../../parameters/ifMatchHeaderParamHash.yml' |
| - $ref: '../../parameters/ifNoneMatchHeaderParam.yml' |
| - $ref: '../../parameters/requestedAcksParam.yml' |
| - $ref: '../../parameters/timeoutParam.yml' |
| - $ref: '../../parameters/responseRequiredParam.yml' |
| 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: '../../schemas/features/features.yml' |
| example: |
| { |
| "featureId1": { |
| "definition": [ "namespace:definition1:v1.0" ], |
| "properties": { "property1": "value1" } |
| }, |
| "featureId2": { |
| "definition": [ "namespace:definition2:v1.0" ], |
| "properties": { "property2": "value2" } |
| } |
| } |
| '304': |
| $ref: '../../responses/notModified.yml' |
| '400': |
| description: |- |
| The request could not be completed. Possible reasons: |
| * the `thingId` does not conform to the namespaced entity ID notation (see [Ditto documentation on namespaced entity IDs](https://www.eclipse.org/ditto/basic-namespaces-and-names.html#namespaced-id)). |
| * at least one of the defined query parameters is invalid. |
| content: |
| application/json: |
| schema: |
| $ref: '../../schemas/errors/advancedError.yml' |
| '401': |
| description: The request could not be completed due to missing authentication. |
| content: |
| application/json: |
| schema: |
| $ref: '../../schemas/errors/advancedError.yml' |
| '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: '../../schemas/errors/advancedError.yml' |
| '412': |
| $ref: '../../responses/preconditionFailed.yml' |
| put: |
| summary: Create or modify all features of a specific thing at once |
| description: |- |
| Create or modify all features of a thing identified by the `thingId` path parameter. |
| |
| ### Create all features at once |
| In case at the initial creation of your thing you have not specified any features, these can be created here. |
| |
| ### Update all features at once |
| To update all features at once prepare the JSON body accordingly. |
| |
| Note: In contrast to the "PUT thing" request, a partial update is not supported here, |
| but the content will be **overwritten**. |
| If you need to update single features or their paths, please use the sub-resources instead. |
| |
| ### Example: |
| |
| ``` |
| { |
| "coffee-brewer": { |
| "definition": ["com.acme:coffeebrewer:0.1.0"], |
| "properties": { |
| "brewed-coffees": 0 |
| } |
| }, |
| "water-tank": { |
| "properties": { |
| "configuration": { |
| "smartMode": true, |
| "brewingTemp": 87, |
| "tempToHold": 44, |
| "timeoutSeconds": 6000 |
| }, |
| "status": { |
| "waterAmount": 731, |
| "temperature": 44 |
| } |
| } |
| } |
| } |
| ``` |
| tags: |
| - Features |
| parameters: |
| - $ref: '../../parameters/thingIdPathParam.yml' |
| - $ref: '../../parameters/ifMatchHeaderParamHash.yml' |
| - $ref: '../../parameters/ifNoneMatchHeaderParam.yml' |
| - $ref: '../../parameters/requestedAcksParam.yml' |
| - $ref: '../../parameters/timeoutParam.yml' |
| - $ref: '../../parameters/responseRequiredParam.yml' |
| 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: '../../schemas/features/features.yml' |
| example: |
| {} |
| '204': |
| description: The features were successfully modified. |
| headers: |
| ETag: |
| description: |- |
| The (current server-side) ETag for this (sub-)resource. For top-level resources it is in the format |
| "rev:[revision]", for sub-resources it has the format "hash:[calculated-hash]". |
| schema: |
| type: string |
| '400': |
| description: |- |
| The request could not be completed. Possible reasons: |
| * the `thingId` does not conform to the namespaced entity ID notation (see [Ditto documentation on namespaced entity IDs](https://www.eclipse.org/ditto/basic-namespaces-and-names.html#namespaced-id)). |
| * the JSON body of the feature to be created/modified is invalid |
| content: |
| application/json: |
| schema: |
| $ref: '../../schemas/errors/advancedError.yml' |
| '401': |
| description: The request could not be completed due to missing authentication. |
| content: |
| application/json: |
| schema: |
| $ref: '../../schemas/errors/advancedError.yml' |
| '403': |
| description: |- |
| The request could not be completed. Possible reasons: |
| * the caller has insufficient permissions. |
| For modifying all features of an existing thing, `WRITE` permission is required. |
| content: |
| application/json: |
| schema: |
| $ref: '../../schemas/errors/advancedError.yml' |
| '404': |
| description: |- |
| The request could not be completed. The thing with the given ID was not found. |
| content: |
| application/json: |
| schema: |
| $ref: '../../schemas/errors/advancedError.yml' |
| '412': |
| $ref: '../../responses/preconditionFailed.yml' |
| '413': |
| $ref: '../../responses/entityTooLarge.yml' |
| requestBody: |
| content: |
| application/json: |
| schema: |
| $ref: '../../schemas/features/features.yml' |
| example: { |
| "coffee-brewer": { |
| "properties": { |
| "definition": [ "com.acme:coffeebrewer:0.1.0" ], |
| "brewed-coffees": 0 |
| } |
| }, |
| "water-tank": { |
| "properties": { |
| "configuration": { |
| "smartMode": true, |
| "brewingTemp": 87, |
| "tempToHold": 44, |
| "timeoutSeconds": 6000 |
| }, |
| "status": { |
| "waterAmount": 731, |
| "temperature": 44 |
| } |
| } |
| } |
| } |
| description: |- |
| JSON object of all features to be modified at once. Consider that the value has to be a JSON object or null. |
| |
| Examples: |
| * an empty object: {} - would just delete all old features |
| * an empty feature: { "featureId": {} } - We strongly recommend to use a restricted set of characters |
| for the `featureId`, as it might be needed for the (URL) path later. |
| |
| Currently these identifiers should follow the pattern: [_a-zA-Z][_a-zA-Z0-9-]* |
| |
| * a nested object with multiple features as shown in the example value field |
| |
| required: true |
| patch: |
| summary: Patch all features of a specific thing |
| description: |- |
| Patch all features of a thing identified by the `thingId` path parameter. |
| |
| The existing features will be merged with the JSON content set in the request body. |
| |
| Notice that the `null` value has a special meaning and can be used to delete specific features from the thing. |
| For further documentation see [RFC 7396](https://tools.ietf.org/html/rfc7396). |
| |
| **Note**: In contrast to the "PUT thing/{thingId}/features" request, a partial update is supported here |
| and request body is merged with the existing features. |
| |
| ### Example |
| |
| The following example will add/update the properties `brewed-coffees`, `tempToHold` and `failState`. |
| The configuration property `smartMode` will be deleted from the thing. |
| |
| |
| ``` |
| { |
| "coffee-brewer": { |
| "properties": { |
| "brewed-coffees": 10 |
| } |
| }, |
| "water-tank": { |
| "properties": { |
| "configuration": { |
| "smartMode": null, |
| "tempToHold": 50, |
| }, |
| "status": { |
| "failState": true |
| } |
| } |
| } |
| } |
| ``` |
| tags: |
| - Features |
| parameters: |
| - $ref: '../../parameters/thingIdPathParam.yml' |
| - $ref: '../../parameters/featureIdPathPathParam.yml' |
| - $ref: '../../parameters/ifMatchHeaderParamHash.yml' |
| - $ref: '../../parameters/ifNoneMatchHeaderParam.yml' |
| - $ref: '../../parameters/requestedAcksParam.yml' |
| - $ref: '../../parameters/timeoutParam.yml' |
| - $ref: '../../parameters/responseRequiredParam.yml' |
| responses: |
| '204': |
| description: The features were successfully patched. |
| headers: |
| ETag: |
| description: |- |
| The (current server-side) ETag for this (sub-)resource. For top-level resources it is in the format |
| "rev:[revision]", for sub-resources it has the format "hash:[calculated-hash]". |
| schema: |
| type: string |
| '400': |
| description: |- |
| The request could not be completed. Possible reasons: |
| * the `thingId` does not conform to the namespaced entity ID notation (see [Ditto documentation on namespaced entity IDs](https://www.eclipse.org/ditto/basic-namespaces-and-names.html#namespaced-id)). |
| * the JSON body of the feature to be created/modified is invalid |
| content: |
| application/json: |
| schema: |
| $ref: '../../schemas/errors/advancedError.yml' |
| '401': |
| description: The request could not be completed due to missing authentication. |
| content: |
| application/json: |
| schema: |
| $ref: '../../schemas/errors/advancedError.yml' |
| '403': |
| description: |- |
| The request could not be completed. Possible reasons: |
| * the caller has insufficient permissions. |
| For modifying all features of an existing thing, `WRITE` permission is required. |
| content: |
| application/json: |
| schema: |
| $ref: '../../schemas/errors/advancedError.yml' |
| '404': |
| description: |- |
| The request could not be completed. The thing with the given ID was not found. |
| content: |
| application/json: |
| schema: |
| $ref: '../../schemas/errors/advancedError.yml' |
| '412': |
| $ref: '../../responses/preconditionFailed.yml' |
| '413': |
| $ref: '../../responses/entityTooLarge.yml' |
| requestBody: |
| content: |
| application/merge-patch+json: |
| schema: |
| $ref: '../../schemas/features/features.yml' |
| example: |
| coffee-brewer: |
| properties: |
| brewed-coffees: 10 |
| water-tank: |
| properties: |
| configuration: |
| smartMode: null |
| tempToHold: 50 |
| status: |
| failState: true |
| description: |- |
| JSON object of all features to be patched. Consider that the value has to be a [JSON merge patch](https://tools.ietf.org/html/rfc7396). |
| |
| Examples: |
| * a nested object with multiple features as shown in the example value field |
| |
| * **Note**: To delete certain entries of a feature the `null` value can be used. |
| For further documentation see [RFC 7396](https://tools.ietf.org/html/rfc7396). |
| required: true |
| delete: |
| summary: Delete all features of a specific thing |
| description: |- |
| Deletes all features of the thing identified by the `thingId` path parameter. |
| tags: |
| - Features |
| parameters: |
| - $ref: '../../parameters/thingIdPathParam.yml' |
| - $ref: '../../parameters/ifMatchHeaderParamHash.yml' |
| - $ref: '../../parameters/ifNoneMatchHeaderParam.yml' |
| - $ref: '../../parameters/requestedAcksParam.yml' |
| - $ref: '../../parameters/timeoutParam.yml' |
| - $ref: '../../parameters/responseRequiredParam.yml' |
| responses: |
| '204': |
| description: The features were successfully deleted. |
| '400': |
| description: |- |
| The request could not be completed. Possible reasons: |
| * the `thingId` does not conform to the namespaced entity ID notation (see [Ditto documentation on namespaced entity IDs](https://www.eclipse.org/ditto/basic-namespaces-and-names.html#namespaced-id)). |
| content: |
| application/json: |
| schema: |
| $ref: '../../schemas/errors/advancedError.yml' |
| '401': |
| description: The request could not be completed due to missing authentication. |
| content: |
| application/json: |
| schema: |
| $ref: '../../schemas/errors/advancedError.yml' |
| '403': |
| description: |- |
| The request could not be completed. Possible reasons: |
| * the caller has insufficient permissions. |
| For deleting all features of an existing thing, `WRITE` permission is required. |
| content: |
| application/json: |
| schema: |
| $ref: '../../schemas/errors/advancedError.yml' |
| '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: '../../schemas/errors/advancedError.yml' |
| '412': |
| $ref: '../../responses/preconditionFailed.yml' |