asyncapi: 2.0.0
info:
  version: 3.1.0
  x-visibility: external
  title: Commanding Async API
  description: |
    Commanding Async API defines topics and message structures to receive MQTT commands to be executed by the clients and send the command execution status.

servers:
   EU1:
    url: 'mindconnectmqtt.<private-cloud-domain>:8883'
    description: |
      MQTT Broker for MindSphere which offers below described topics.
    protocol: mqtt

channels:
  tc/{tenantId}/{clientId}/i/cmd_v3/c:
    parameters:
      tenantId:
        $ref: '#/components/parameters/TenantId'
      clientId:
        $ref: '#/components/parameters/ClientId'
    subscribe:
      operationId: createCommandMessage
      description: |
         Recieve the command to be executed by the client.
      tags:
        - name: Commanding Operations
      message:
        summary: Command Request Message
        $ref: '#/components/messages/CommandRequestMessage'
  tc/{tenantId}/{clientId}/o/cmd_v3/u:
    parameters:
      tenantId:
        $ref: '#/components/parameters/TenantId'
      clientId:
        $ref: '#/components/parameters/ClientId'
    publish:
      operationId: commandResponseMessage
      description: |
         Send the command execution status and progress.
      tags:
        - name: Commanding Operations
      message:
        summary: Command Request Message
        $ref: '#/components/messages/CommandResponseMessage'

components:
  messages:
    CommandRequestMessage:
      name: Command Request Message
      description: |
        Message containing the command request parameters.
      payload:
        $ref: '#/components/schemas/CommandRequestMessage'
    CommandResponseMessage:
      name: Command Response Message
      description: |
        Message conatining the command response parameters.
      payload:
        $ref: '#/components/schemas/CommandResponseMessage'


  schemas:
    CommandRequestMessage:
      title: Command
      type: object
      required:
        - id
        - data
      properties:
        id:
          type: string
          example: 99609765fed2452c8e126814c283a27f
          description: Unique id of message.
        data:
          type: object
          required:
            - jobId
            - createdAt
            - payload
          description:  Structure containing the command payload and metadata information to be sent to the client.
          properties:
            jobId:
              type: string
              example: 21349765fe45652c8e126814c283a114
              description: Unique identifier of the job.
            createdAt:
              type: string
              description: Time at which the job was created. ( In UTC format )
              example: "2011-08-10T20:17:46.384Z"
            payload:
              type: object
              description: Data containing the command payload to be executed by the client. Maximum payload size is restricted to 4kB.
              additionalProperties:
                type: string

    CommandResponseMessage:
      title: Command
      type: object
      required:
        - id
        - requestId
        - data
      properties:
        id:
          type: string
          example: 11609765fed2452c8e126814c283a289
          description: Unique id of message.
        requestId:
          type: string
          example: 99609765fed2452c8e126814c283a27f
          description: Id of the command request message that triggered the command execution.
          readOnly: true
        data:
          type: object
          required:
            - timestamp
            - jobId
            - status
            - response
          description:  Structure containing the command response payload and metadata information.
          properties:
             timestamp:
                type: string
                example: "2011-08-12T20:17:46.384Z"
                description: Time at which response was generated. Should be in UTC format.
                readOnly: true
             jobId:
                type: string
                example: 21349765fe45652c8e126814c283a114
                description: Unique identifier of the job.
                readOnly: true
             status:
                type: string
                enum:
                  - EXECUTING
                  - EXECUTED
                  - FAILED
                  - CANCELED
                description: Status of the command execution.
             response:
                type: object
                description: Data containing the command response received from the client after the command execution. Maximum response size is restricted to 4kB.
                additionalProperties:
                  type: string
  parameters:
    ClientId:
      description:
        MQTT client id. It is the unique identifier of the device.
      schema:
        type: string
        example: mytenant_201541ad38a4495a96e2021c762b647f
    TenantId:
      description:
        Id of the tenant to which the client belongs to.
      schema:
        type: string
        example: mytenant
