---
asyncapi: 3.0.0
id: 'pionix:de:everest:entrypoint_API'
info:
  title: 'EVerest API definition for the API entrypoint interface'
  version: 1.0.0
  description: >-
    API for EVerest API clients discovering the EVerest API capabilities.

  license:
    name: Apache-2.0
    url: https://opensource.org/licenses/Apache-2.0
  tags:
    - name: EVerest
    - name: Auth
servers:
  default:
    pathname: 'everest_api/'
    host: 'localhost:1883'
    description: default local MQTT
    protocol: mqtt
defaultContentType: application/json


channels:
  send_request_discover:
    address: 'discover'
    messages:
      send_request_discover:
        $ref: '#/components/messages/send_request_discover'
  receive_reply_discover:
    address: null
    messages:
      receive_reply_discover:
        $ref: '#/components/messages/receive_reply_discover'
  send_request_query_module:
    address: 'query-modules/{api_type}'
    parameters:
      api_type:
        description: The type of API to query
    messages:
      send_request_query_module:
        $ref: '#/components/messages/send_request_query_module'
  receive_reply_query_module:
    address: null
    messages:
      receive_reply_query_module:
        $ref: '#/components/messages/receive_reply_query_module'

  send_ready_beacon:
    address: 'ready_beacon'
    messages:
      send_ready_beacon:
        $ref: '#/components/messages/send_ready_beacon'


operations:
  send_request_discover:
    title: 'Request API capability discovery.'
    action: send
    channel:
      $ref: '#/channels/send_request_discover'
    description: >-
      Allow API clients to discover the available capabilities of the API.
      Reply will not be monolithic but come in as many messages as there are modules.
    reply:
      address:
        location: "$message.header#/replyTo"
      channel:
        $ref: '#/channels/receive_reply_discover'
  receive_reply_discover:
    title: 'Reply to discover request'
    action: receive
    channel:
      $ref: '#/channels/receive_reply_discover'
  send_request_query_module:
    title: 'Request all modules that implement {api_type} to reveal their API parameters.'
    action: send
    channel:
      $ref: '#/channels/send_request_query_module'
    description: >-
      Allow API clients to discover specific types of APIs.
      Reply will not be monolithic but come in as many messages as there a matching modules.
    reply:
      address:
        location: "$message.header#/replyTo"
      channel:
        $ref: '#/channels/receive_reply_query_module'
  receive_reply_query_module:
    title: 'Reply to query modules request'
    action: receive
    channel:
      $ref: '#/channels/receive_reply_query_module'

  send_ready_beacon:
    title: 'Send Ready Beacon'
    action: send
    channel:
      $ref: '#/channels/send_ready_beacon'


components:
  messages:
    send_request_discover:
      name: send_request_discover
      title: 'Discover API'
      contentType: application/json
      payload:
        type: object
        properties:
          headers:
            type: object
            properties:
              replyTo:
                type: string
                description: Address to send the response to.
      examples:
        - summary: "requesting available APIs"
          payload:
            headers:
              replyTo: your/arbitrary/reply/topic
    receive_reply_discover:
      name: receive_reply_discover
      title: 'Reply to request to discover the API'
      summary: 'Reply to request to discover the API.'
      contentType: application/json
      payload:
         $ref: '#/components/schemas/ApiDiscoverResponse'
      examples:
        - summary: "Reply from each module is an array of (id, type, <version>) tuples"
          payload:
            apis:
              - module_id: "module_1"
                type: "display_message"
                version: 1
              - module_id: "module_1"
                type: "session_cost_consumer"
                version: 1
    send_request_query_module:
      name: send_request_query_module
      title: 'Query API modules'
      contentType: application/json
      payload:
        type: object
        properties:
          headers:
            type: object
            properties:
              replyTo:
                type: string
                description: Address to send the response to.
      examples:
        - summary: "requesting available APIs of type {api_type}"
          payload:
            headers:
              replyTo: your/arbitrary/reply/topic
    receive_reply_query_module:
      name: receive_reply_query_module
      title: 'Reply to request to query module'
      summary: 'Reply to request to query module.'
      contentType: application/json
      payload:
         $ref: '#/components/schemas/ApiDiscoverResponse'
      examples:
        - summary: "Reply from each module is an array of (id, type, <version>) tuples"
          payload:
            apis:
              - module_id: "dm_1"
                type: "display_message"
                version: 1

    send_ready_beacon:
      name: send_ready_beacon
      title: 'Send ready beacon'
      summary: A beacon to indicate the API is ready to be queried
      contentType: application/json
      payload:
        $ref: '#/components/schemas/ReadyBeacon'
      examples:
        - summary: "Ready Beacon"
          payload: {}


  schemas:
    ApiDiscoverResponse:
      description: Type for API discovery results
      type: object
      additionalProperties: true
      required:
        - apis
      properties:
        apis:
          description: Array of API parameters
          type: array
          items:
            type: object
            $ref: '#/components/schemas/ApiParameter'
    ApiParameter:
      description: Parameters for a single API
      type: object
      additionalProperties: true
      required:
        - type
        - module_id
        - version
      properties:
        type:
          type: string
        module_id:
          type: string
        version:
          type: integer
        communication_monitoring:
          type: object
          $ref: '#/components/schemas/CommunicationParameters'
    CommunicationParameters:
      description: Parameters of the communication monitoring between EVerest and client
      type: object
      additionalProperties: true
      properties:
        heartbeat_period_ms:
          description: Period of heartbeat messages from EVerest to the client
          type: integer
        communication_check_period_s:
          description: Maximum expected interval for alive messages from client to EVerest
          type: integer
        request_reply_timeout_s:
          description: Timeout within which a client must reply to request from EVerest
          type: integer

    ReadyBeacon:
      type: object
      additionalProperties: true
      description: a beacon to indicate the API is ready to be queried