index.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 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'
    - $ref: '../../parameters/conditionParam.yml'
    - $ref: '../../parameters/channelParam.yml'
    - $ref: '../../parameters/liveChannelConditionParam.yml'
    - $ref: '../../parameters/liveChannelTimeoutStrategyParam.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
        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/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'
    - $ref: '../../parameters/conditionParam.yml'
    - $ref: '../../parameters/channelParam.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'
    '424':
      $ref: '../../responses/dependencyFailed.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/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 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'
    '424':
      $ref: '../../responses/dependencyFailed.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'
    - $ref: '../../parameters/conditionParam.yml'
    - $ref: '../../parameters/channelParam.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'
    '424':
      $ref: '../../responses/dependencyFailed.yml'