magistrala/apidocs/asyncapi/websocket.yaml

# Copyright (c) Abstract Machines
# SPDX-License-Identifier: Apache-2.0

asyncapi: 2.6.0
id: 'https://github.com/absmach/magistrala/blob/main/api/asyncapi/websocket.yaml'
info:
  title: Magistrala WebSocket adapter
  description: WebSocket adapter provides a WebSocket API for sending messages through communication channels. WebSocket adapter uses [mProxy](https://github.com/absmach/mproxy) for proxying traffic between client and MQTT broker.
  version: '0.18.0'
  contact:
    name: Magistrala Team
    url: 'https://github.com/absmach/magistrala'
    email: info@absmach.eu
  license:
    name: Apache 2.0
    url: 'https://github.com/absmach/magistrala/blob/main/LICENSE'
tags:
  - name: WebSocket
defaultContentType: application/json

servers:
  dev:
    url: 'ws://{host}:{port}'
    protocol: ws
    description: Default WebSocket Adapter URL
    variables:
      host:
        description: Hostname of the WebSocket adapter
        default: localhost
      port:
        description: Magistrala WebSocket Adapter port
        default: '8008'

channels:
  'm/{domainPrefix}/c/{channelPrefix}/{subtopic}':
    parameters:
      domainPrefix:
        $ref: '#/components/parameters/domainPrefix'
        in: path
        required: true
      channelPrefix:
        $ref: '#/components/parameters/channelPrefix'
        in: path
        required: true
      subtopic:
        $ref: '#/components/parameters/subtopic'
        in: path
        required: false
    publish:
      summary: Publish messages to a channel
      operationId: publishToChannel
      message:
        $ref: '#/components/messages/jsonMsg'
        messageId: publishMessage
      bindings:
        ws:
          method: POST
          query:
            subtopic: '{$request.query.subtopic}'
      security:
        - bearerAuth: []
    subscribe:
      summary: Subscribe to receive messages from a channel
      operationId: subscribeToChannel
      message:
        $ref: '#/components/messages/jsonMsg'
        messageId: subscribeMessage
      bindings:
        ws:
          method: GET
          query:
            subtopic: '{$request.query.subtopic}'
      security:
        - bearerAuth: []
  /version:
    subscribe:
      summary: Get the version of the Magistrala adapter
      operationId: getVersion
      bindings:
        http:
          method: GET
  metrics:
    description: Endpoint for getting service metrics.
    subscribe:
      operationId: metrics
      summary: Service metrics
    bindings:
      http:
        type: request
        method: GET

components:
  messages:
    jsonMsg:
      title: JSON Message
      summary: Arbitrary JSON array or object.
      contentType: application/json
      payload:
        $ref: '#/components/schemas/jsonMsg'
  schemas:
    jsonMsg:
      type: object
      description: Arbitrary JSON object or array. SenML format is recommended.
      example: >
        ### SenML

        ```json

        [{"bn":"some-base-name:","bt":1641646520, "bu":"A","bver":5,
        "n":"voltage","u":"V","v":120.1}, {"n":"current","t":-5,"v":1.2},
        {"n":"current","t":-4,"v":1.3}]

        ```

        ### JSON

        ```json

        {"field_1":"val_1", "t": 1641646525}

        ```

        ### JSON Array

        ```json

        [{"field_1":"val_1", "t": 1641646520},{"field_2":"val_2", "t":
        1641646522}]

        ```
  parameters:
    domainPrefix:
      description: ID or route of the domain associated with the channel and client.
      schema:
        type: string
    channelPrefix:
      description: ID or route of the channel connected to the Client ID defined in the username.
      schema:
        type: string
    subtopic:
      description: Arbitrary message subtopic.
      schema:
        type: string
        default: ''
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: uuid
      description: |
        * Client access: "Authorization: Client <client_key>"