2.0/openapi/sources/paths/things/attribute.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: 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).

    ### Example:

    In order to retrieve the `name` field of an `manufacturer` attribute, the full path would be
    `/things/{thingId}/attributes/manufacturer/name`
  tags:
    - Things
  parameters:
    - $ref: '../../parameters/thingIdPathParam.yml'
    - $ref: '../../parameters/attributePathPathParam.yml'
    - $ref: '../../parameters/ifMatchHeaderParamHash.yml'
    - $ref: '../../parameters/ifNoneMatchHeaderParam.yml'
    - $ref: '../../parameters/timeoutParam.yml'
  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: '../../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)).
      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 or
        the attribute at the specified path was not found.
      content:
        application/json:
          schema:
            $ref: '../../schemas/errors/advancedError.yml'
    '412':
      $ref: '../../responses/preconditionFailed.yml'
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.

    * If you specify a new attribute path, this will be created
    * If you specify an existing attribute path, this will be updated

    The attribute (JSON) can be referenced hierarchically, by applying JSON Pointer notation (RFC-6901).

    ### Example:

    In order to put the `name` field of an `manufacturer` attribute, the full path would be
    `/things/{thingId}/attributes/manufacturer/name`
  tags:
    - Things
  parameters:
    - $ref: '../../parameters/thingIdPathParam.yml'
    - $ref: '../../parameters/attributePathPathParam.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 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. 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 modifying an attribute 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:
    $ref: '../../requests/value.yml'
patch:
  summary: Patch a specific attribute of a specific thing
  description: |-
    Patch a specific attribute of a thing identified by the `thingId` path parameter.

    * If you specify a new attribute path, this will be created
    * If you specify an existing attribute path, this will be merged
    * If you set the request body to `null` for an existing attribute path then the attribute will be deleted.
      For further documentation see [RFC 7396](https://tools.ietf.org/html/rfc7396).

    The attribute (JSON) can be referenced hierarchically, by applying JSON Pointer notation (RFC-6901).

    ### Example:

    In order to patch the `name` field of an `manufacturer` attribute, the full path would be
    `/things/{thingId}/attributes/manufacturer/name`
  tags:
    - Things
  parameters:
    - $ref: '../../parameters/thingIdPathParam.yml'
    - $ref: '../../parameters/attributePathPathParam.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 attribute was 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)).
      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 an attribute 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:
    $ref: '../../requests/patchValue.yml'
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).

    ### Example:
    In order to delete the `name` field of an `manufacturer` attribute, the full path would be
    `/things/{thingId}/attributes/manufacturer/name`
  tags:
    - Things
  parameters:
    - $ref: '../../parameters/thingIdPathParam.yml'
    - $ref: '../../parameters/attributePathPathParam.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 attribute was 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 a single attribute 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 or the attribute at the specified path was not found.
      content:
        application/json:
          schema:
            $ref: '../../schemas/errors/advancedError.yml'
    '412':
      $ref: '../../responses/preconditionFailed.yml'