desiredProperties.yml

# 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 desired properties of a feature
  description: |-
    Returns all desired properties of the feature identified by the `thingId` and `featureId` path parameter.
  tags:
    - Features
  parameters:
    - $ref: '../../parameters/thingIdPathParam.yml'
    - $ref: '../../parameters/featureIdPathPathParam.yml'
    - $ref: '../../parameters/desiredPropertiesFieldsQueryParam.yml'
    - $ref: '../../parameters/ifMatchHeaderParamHash.yml'
    - $ref: '../../parameters/ifNoneMatchHeaderParam.yml'
    - $ref: '../../parameters/getMetadataParam.yml'
    - $ref: '../../parameters/timeoutParam.yml'
    - $ref: '../../parameters/conditionParam.yml'
    - $ref: '../../parameters/channelParam.yml'
    - $ref: '../../parameters/liveChannelConditionParam.yml'
    - $ref: '../../parameters/liveChannelTimeoutStrategyParam.yml'
  responses:
    '200':
      description: The desired properties were successfully retrieved.
      headers:
        ETag:
          description: |-
            The (current server-side) ETag for this (sub-)resource. For top-level resources it is in the format
            "rev:[revision]", for sub-resources it has the format "hash:[calculated-hash]".
          schema:
            type: string
        live-channel-condition-matched:
          description: |-
            Whether or not the live-channel-condition did match and the thing was retrieved from the device.
          schema:
            type: boolean
        channel:
          description: |-
            The cannel which was used to retrieve the thing.
          schema:
            type: string
      content:
        application/json:
          schema:
            $ref: '../../schemas/features/featureProperties.yml'
    '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 specified feature has no desired properties or
        the thing with the specified `thingId` or the feature with `featureId` was not found.
      content:
        application/json:
          schema:
            $ref: '../../schemas/errors/advancedError.yml'
    '412':
      $ref: '../../responses/preconditionFailed.yml'
put:
  summary: Create or update all desired properties of a feature at once
  description: |-
    Create or update the desired properties of a feature identified by the `thingId` and `featureId` path parameter.

    The desired properties will be overwritten with the JSON content from the request body.
  tags:
    - Features
  parameters:
    - $ref: '../../parameters/thingIdPathParam.yml'
    - $ref: '../../parameters/featureIdPathPathParam.yml'
    - $ref: '../../parameters/ifMatchHeaderParamHash.yml'
    - $ref: '../../parameters/ifNoneMatchHeaderParam.yml'
    - $ref: '../../parameters/putMetadataParam.yml'
    - $ref: '../../parameters/deleteMetadataParam.yml'
    - $ref: '../../parameters/requestedAcksParam.yml'
    - $ref: '../../parameters/timeoutParam.yml'
    - $ref: '../../parameters/responseRequiredParam.yml'
    - $ref: '../../parameters/conditionParam.yml'
    - $ref: '../../parameters/channelParam.yml'
  responses:
    '201':
      description: The desired properties were successfully created.
      headers:
        ETag:
          description: |-
            The (current server-side) ETag for this (sub-)resource. For top-level resources it is in the format
            "rev:[revision]", for sub-resources it has the format "hash:[calculated-hash]".
          schema:
            type: string
      content:
        application/json:
          schema:
            $ref: '../../schemas/features/featureProperties.yml'
    '204':
      description: The desired properties were successfully updated.
      headers:
        ETag:
          description: |-
            The (current server-side) ETag for this (sub-)resource. For top-level resources it is in the format
            "rev:[revision]", for sub-resources it has the format "hash:[calculated-hash]".
          schema:
            type: string
    '400':
      description: |-
        The request could not be completed. Possible reasons:
          * the `thingId` does not conform to the namespaced entity ID notation (see [Ditto documentation on namespaced entity IDs](https://www.eclipse.org/ditto/basic-namespaces-and-names.html#namespaced-id)).
          * the JSON body of the desired feature roperties to be created/modified is invalid
      content:
        application/json:
          schema:
            $ref: '../../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 the desired properties of an existing feature, `WRITE` permission is required.
      content:
        application/json:
          schema:
            $ref: '../../schemas/errors/advancedError.yml'
    '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: '../../schemas/errors/advancedError.yml'
    '412':
      $ref: '../../responses/preconditionFailed.yml'
    '413':
      $ref: '../../responses/entityTooLarge.yml'
    '424':
      $ref: '../../responses/dependencyFailed.yml'
  requestBody:
    content:
      application/json:
        schema:
          $ref: '../../schemas/features/featureProperties.yml'
        example: {
          "configuration": {
            "smartMode": true,
            "brewingTemp": 87,
            "tempToHold": 44,
            "timeoutSeconds": 6000
          },
          "status": {
            "waterAmount": 731,
            "temperature": 44
          }
        }
    description: |-
      JSON object of all desried properties to be updated at once.

      Consider that the value has to be a JSON object or `null`. We strongly recommend to use
      a restricted set of characters for the key (identifier).

      Currently these identifiers should follow the pattern: [_a-zA-Z][_a-zA-Z0-9\-]*

    required: true
patch:
  summary: Patch all desired properties of a feature
  description: |-
    Patch the desired properties of a feature identified by the `thingId` and `featureId` path parameter.

    The existing desired properties will be merged with the JSON content set in the request body.

    Notice that the `null` value can be used to delete the whole feature or specific parts of it.
    For further documentation see [RFC 7396](https://tools.ietf.org/html/rfc7396).

    **Note**: In contrast to the "PUT things/{thingId}/features/{featureId}/desiredProperties" request,
    a partial update is supported here and request body is merged with the existing desired properties.
  tags:
    - Features
  parameters:
    - $ref: '../../parameters/thingIdPathParam.yml'
    - $ref: '../../parameters/featureIdPathPathParam.yml'
    - $ref: '../../parameters/ifMatchHeaderParamHash.yml'
    - $ref: '../../parameters/ifNoneMatchHeaderParam.yml'
    - $ref: '../../parameters/putMetadataParam.yml'
    - $ref: '../../parameters/deleteMetadataParam.yml'
    - $ref: '../../parameters/requestedAcksParam.yml'
    - $ref: '../../parameters/timeoutParam.yml'
    - $ref: '../../parameters/responseRequiredParam.yml'
    - $ref: '../../parameters/conditionParam.yml'
    - $ref: '../../parameters/channelParam.yml'
  responses:
    '204':
      description: The desired properties 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 desired feature roperties 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 the desired properties of an existing feature, `WRITE` permission is required.
      content:
        application/json:
          schema:
            $ref: '../../schemas/errors/advancedError.yml'
    '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: '../../schemas/errors/advancedError.yml'
    '412':
      $ref: '../../responses/preconditionFailed.yml'
    '413':
      $ref: '../../responses/entityTooLarge.yml'
    '424':
      $ref: '../../responses/dependencyFailed.yml'
  requestBody:
    content:
      application/merge-patch+json:
        schema:
          $ref: '../../schemas/features/featureProperties.yml'
        example:
          configuration:
            smartMode: null
            brewingTemp: 87
            tempToHold: 44
            timeoutSeconds: 6000
          status:
            waterAmount: 731
            temperature: 44
    description: |-
      JSON object of all desried properties to be patched.

      Consider that the value has to be a [JSON merge patch](https://tools.ietf.org/html/rfc7396). We strongly recommend to use
      a restricted set of characters for the key (identifier).

      Currently these identifiers should follow the pattern: [_a-zA-Z][_a-zA-Z0-9\-]*
    required: true
delete:
  summary: Delete all desired properties of a feature
  description: |-
    Deletes all desired properties of the feature identified by the `thingId` and `featureId` path parameter.
  tags:
    - Features
  parameters:
    - $ref: '../../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'
    - $ref: '../../parameters/conditionParam.yml'
    - $ref: '../../parameters/channelParam.yml'
  responses:
    '204':
      description: The desired properties were successfully deleted.
    '400':
      description: |-
        The request could not be completed. Possible reasons:
          * the `thingId` does not conform to the namespaced entity ID notation (see [Ditto documentation on namespaced entity IDs](https://www.eclipse.org/ditto/basic-namespaces-and-names.html#namespaced-id)).
      content:
        application/json:
          schema:
            $ref: '../../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 the desired properties of an existing feature, `WRITE` permission is required.
      content:
        application/json:
          schema:
            $ref: '../../schemas/errors/advancedError.yml'
    '404':
      description: |-
        The request could not be completed. The specified feature has no desired properties or
        the thing with the specified `thingId` or the feature with `featureId` was not found.
      content:
        application/json:
          schema:
            $ref: '../../schemas/errors/advancedError.yml'
    '412':
      $ref: '../../responses/preconditionFailed.yml'
    '424':
      $ref: '../../responses/dependencyFailed.yml'