asyncapi: 3.0.0
id: urn:ie:ai:assetmanager
info:
  title: AI Asset Manager AWS Cloud Package Delivery API
  version: "2.3.0"
  description: |
    AI Asset Manager AWS Cloud Package Delivery API defines the channels and messages used for a package delivery from cloud clients to the AI Asset Manager.

    **Package delivery flow**
    - Prerequisites: AWS cloud integration workspace in AIMM, a package ready to download via HTTP(S)
    - The delivery is initiated from the cloud side with the #New Delivery operation.
    - After AIMM received the new delivery request, then it makes a request for the url to the downloadable package with #Presigned URL Link Request
    - The cloud side user reply to the url request with #Presigned URL Link Response. AIMM waits a configurable amount of time (default 10s) to the url response before times out. In that case AIMM try to request a new url (up to a configurable amount of times, default is 3)
    - If AIMM received the url, it tries to download that and publishes the "Downloading" state, if the download has some kind of retryable error a new url request will be made (with the same retry count configuration as before).
    - If the package is downloaded, a package import will be attempted to the AIMM workspace, the "Importing" state is published.
    - If everything is completed, "Success" state will published, otherwise "Error" state, in both case the delivery flow is terminated.

    **General**
    - All channels (topics) listed in this document are prefixed with a server dependent part marked as `{channelPrefix}`.
    The actual value of the {channelPrefix} is specified under the "URL variables" section of the given server.

servers:
  aws-tls:
    host: "{account-specific-prefix}.iot.{aws-region}.amazonaws.com:443"
    protocol: tls
    description: AWS IoT Core Broker
    protocolVersion: 3.1.1
    variables:
      account-specific-prefix:
        description: Unique identifier defined by the AWS account
      aws-region:
        description: AWS Region
      channelPrefix:
        description: |
          {projectId}/{targetId}
          - projectId is a unique id identifying a project in the cloud
          - targetId is a unique id to represent an AIMM workspace on the cloud side.  1-project_N-targets


channels:
  "{channelPrefix}/deliveries/${deliveryId}/event/newDelivery":
    parameters:
      $ref: '#/components/schemas/DefaultChannelPrefixParameter'
      deliveryId:
        $ref: '#/components/schemas/DeliveryId'
    # publish:
    #   summary: Initiate a Delivery
    #   description: A client can publish a message on this channel to initiate the Delivery
    #   tags:
    #     - name: New Delivery
    #   message:
    #     $ref: '#/components/messages/NewDelivery'

  "{channelPrefix}/deliveries/${deliveryId}/event/presignedUrlRequest":
    parameters:
      $ref: '#/components/schemas/DefaultChannelPrefixParameter'
      deliveryId:
        $ref: '#/components/schemas/DeliveryId'
    # subscribe:
    #   summary: Presigned URL request for edge configuration package
    #   description: A client can subscribe on this channel to receive Presigned URL requests for edge configuration packages.
    #   tags:
    #     - name: Presigned URL Link Request
    #   message:
    #     $ref: '#/components/messages/PresignedUrlLinkRequest'

  "{channelPrefix}/deliveries/${deliveryId}/data/presignedUrlResponse":
    parameters:
      $ref: '#/components/schemas/DefaultChannelPrefixParameter'
      deliveryId:
        $ref: '#/components/schemas/DeliveryId'
    # publish:
    #   summary: Response to the Presigned URL Request from AI Asset Manager
    #   description: A client can publish a response message on this channel with the Presigned URL Link to the edge configuration package.
    #   tags:
    #     - name: Presigned URL Link Response
    #   message:
    #     $ref: '#/components/messages/PresignedUrlLinkResponse'

  "{channelPrefix}/deliveries/${deliveryId}/data/state":
    parameters:
      $ref: '#/components/schemas/DefaultChannelPrefixParameter'
      deliveryId:
        $ref: '#/components/schemas/DeliveryId'
    # subscribe:
    #   summary: State of the Delivery flow
    #   description: A client can subscribe on this channel to receive messages upon delivery flow state changes. Only Downloading, Importing, Success and Error states are published.
    #   tags:
    #     - name: Delivery State
    #   message:
    #     $ref: '#/components/messages/DeliveryState'

components:
  messages:
    NewDelivery:
      name: NewDeliveryMsg
      contentType: application/json
      payload:
        $ref: '#/components/schemas/NewDeliveryMsgPayload'

    PresignedUrlLinkRequest:
      name: PresignedUrlLinkRequestMsg
      contentType: application/json
      payload:
        $ref: '#/components/schemas/PresignedUrlLinkRequestMsgPayload'

    PresignedUrlLinkResponse:
      name: PresignedUrlLinkResponseMsg
      contentType: application/json
      payload:
        $ref: '#/components/schemas/PresignedUrlLinkResponseMsgPayload'

    DeliveryState:
      name: DeliveryStateInAimmMsg
      contentType: application/json
      payload:
        $ref: '#/components/schemas/DeliveryStateMsgPayload'

  schemas:
    DefaultChannelPrefixParameter:
      channelPrefix:
        description: Server dependent parameter, actual value is specified under the "URL variables" section of the server block.

    ProjectId:
      description: Identifier generated by the client in order to uniquely identify the project on the Cloud Side.

    TargetId:
      description: Identifier generated by the client in order to uniquely identify one AIMM workspace by ID on the cloud side.  1-project_N-targets.

    DeliveryId:
      description: Identifier generated by the client in order to uniquely identify the package delivery flow.

    Timestamp:
      type: string
      format: dateTime
      description: Timestamp when the message was sent using RFC3339 standard date-time format.

    PackageId:
      type: string
      format: uuid
      description: Identifier generated by the client in order to uniquely identify the Package.

    EventId:
      type: string
      format: uuid
      description: Identifier generated by the client in order to uniquely identify the Event.

    PackageVersion:
      type: string
      description: Version number of the uniquely identifiable Package.


    NewDeliveryMsgPayload:
      type: object
      required: [ packageId, eventId, timestamp, packageVersion ]
      properties:
        packageId:
          $ref: '#/components/schemas/PackageId'
        eventId:
          $ref: '#/components/schemas/EventId'
        timestamp:
          $ref: '#/components/schemas/Timestamp'
        packageVersion:
          $ref: '#/components/schemas/PackageVersion'

    PresignedUrlLinkRequestMsgPayload:
      type: object
      required: [ eventId, timestamp ]
      properties:
        eventId:
          $ref: '#/components/schemas/EventId'
        timestamp:
          $ref: '#/components/schemas/Timestamp'
        packageVersion:
          $ref: '#/components/schemas/PackageVersion'

    PresignedUrlLinkResponseMsgPayload:
      type: object
      required: [ timestamp, attributes ]
      properties:
        timestamp:
          $ref: '#/components/schemas/Timestamp'
        attributes:
          type: object
          required: [ presignedUrl ]
          properties:
            presignedUrl:
              type: string
              format: url

    DeliveryStateMsgPayload:
      type: object
      required: [ timestamp, state, attributes ]
      properties:
        timestamp:
          $ref: '#/components/schemas/Timestamp'
        state:
          type: string
          enum:
            - Downloading
            - Importing
            - Success
            - Error
        attributes:
          type: object
          properties:
            code:
              type: string
              description: Short error code of the error that may have occurred
            message:
              type: string
              description: Descriptive message of the Error that may have occurred
        packageVersion:
          $ref: '#/components/schemas/PackageVersion'
