connectionId.yml

# Copyright (c) 2022 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 connection
  description: |-
    Returns the connection identified by the `connectionId` path parameter.
  security:
    - DevOpsBasic: [ ]
  tags:
    - Connections
  parameters:
    - $ref: '../../parameters/connectionIdPathParam.yml'
    - $ref: '../../parameters/connectionFieldsQueryParam.yml'
  responses:
    '200':
      description: The request successfully returned the connection.
      content:
        application/json:
          schema:
            $ref: '../../schemas/connections/connection.yml'
    '400':
      description: |-
        The request could not be completed. The `connectionId` must be an URI.
      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 due to invalid authentication.
      content:
        application/json:
          schema:
            $ref: '../../schemas/errors/advancedError.yml'
    '404':
      description: |-
        The request could not be completed. The connection with ID `connectionId` was not found.
      content:
        application/json:
          schema:
            $ref: '../../schemas/errors/advancedError.yml'
put:
  summary: Create or update a connection with a specified ID
  description: |-
    Update the connection identified by the `connectionId` path parameter.
  security:
    - DevOpsBasic: [ ]
  tags:
    - Connections
  parameters:
    - $ref: '../../parameters/connectionIdPathParam.yml'
  responses:
    '204':
      description: The connection was successfully updated.
    '400':
      description:  >-
        The request could not be completed. Possible reasons:
          * the `connectionId` must be an URI,
          * the `ID` was wrongly set in the request body,
          * the JSON of the connection to be created 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 due to invalid authentication.
      content:
        application/json:
          schema:
            $ref: '../../schemas/errors/advancedError.yml'
    '404':
      description: |-
        The request could not be completed. The connection with ID `connectionId` was not found.
      content:
        application/json:
          schema:
            $ref: '../../schemas/errors/advancedError.yml'
  requestBody:
    content:
      application/json:
        schema:
          $ref: '../../schemas/connections/newConnection.yml'
        example: {
          "name": "hono-example-connection-123",
          "connectionType": "hono",
          "connectionStatus": "open",
          "sources": [
            {
              "addresses": [
                "telemetry",
                "event",
                "..."
              ],
              "authorizationContext": [
                "ditto:inbound-auth-subject",
                "..."
              ],
              "consumerCount": 1,
              "enforcement": {
                "input": "{{ header:device_id }}",
                "filters": [
                  "{{ thing:id }}"
                ]
              },
              "payloadMapping": [
                "Ditto",
                "status"
              ]
            }
          ],
          "targets": [
            {
              "address": "command",
              "topics": [
                "_/_/things/twin/events"
              ],
              "authorizationContext": [
                "ditto:outbound-auth-subject",
                "..."
              ],
              "headerMapping": { }
            }
          ]
        }
    required: true
delete:
  summary: Delete a specific connection
  description: |-
    Delete the connection identified by the `connectionId` path parameter.
  security:
    - DevOpsBasic: [ ]
  tags:
    - Connections
  parameters:
    - $ref: '../../parameters/connectionIdPathParam.yml'
  responses:
    '204':
      description: The connection was successfully deleted.
    '400':
      description:  >-
        The request could not be completed. The `connectionId` must be an URI.
      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 due to an invalid authentication.
      content:
        application/json:
          schema:
            $ref: '../../schemas/errors/advancedError.yml'
    '404':
      description: |-
        The request could not be completed. The connection with ID `connectionId` was not found.
      content:
        application/json:
          schema:
            $ref: '../../schemas/errors/advancedError.yml'