openapi.yaml

openapi: 3.0.3

info:
  title: CasaOS Message Bus API
  version: v2
  description: |
    <picture>
        <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/IceWhaleTech/logo/main/casaos/casaos_banner_dark_night_800px.png">
        <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/IceWhaleTech/logo/main/casaos/casaos_banner_twilight_blue_800px.png">
        <img alt="CasaOS" src="https://raw.githubusercontent.com/IceWhaleTech/logo/main/casaos/casaos_banner_twilight_blue_800px.png">
    </picture>

    CasaOS Message Bus accepts events and actions from various sources and delivers them to subscribers.

    For issues and discussions, please visit the [GitHub repository](https://github.com/IceWhaleTech/CasaOS) or join [our Discord](https://discord.gg/knqAbbBbeX).

servers:
  - url: /v2/message_bus

tags:
  - name: Event methods
    description: |-
      methods for managing event types, as well as publishing and subscribing to events

  - name: Action methods
    description: |-
      methods for managing action types, as well as publishing and subscribing to actions

  - name: Websocket Endpoints
    description: |-
      Endpoint paths for subscribing to events and actions via WebSocket

  - name: SocketIO Endpoints
    description: |-
      Endpoint paths for subscribing to events and actions via SocketIO

  - name: EventType
    description: |-
      <SchemaDefinition schemaRef="#/components/schemas/EventType" />

  - name: Event
    description: |-
      <SchemaDefinition schemaRef="#/components/schemas/Event" />

  - name: ActionType
    description: |-
      <SchemaDefinition schemaRef="#/components/schemas/ActionType" />

  - name: Action
    description: |-
      <SchemaDefinition schemaRef="#/components/schemas/Action" />

  - name: PropertyType
    description: |-
      <SchemaDefinition schemaRef="#/components/schemas/PropertyType" />

x-tagGroups:
  - name: Methods
    tags:
      - EventType methods
      - Event methods
      - ActionType methods
      - Action methods

  - name: Endpoints
    tags:
      - WebSocket Endpoints
      - SocketIO Endpoints

  - name: Schemas
    tags:
      - EventType
      - Event
      - ActionType
      - Action
      - PropertyType

security:
  - access_token: []

paths:
  /event_type:
    get:
      summary: List event types
      description: |
        List all event types that are currently registered with the message bus.
      operationId: getEventTypes
      tags:
        - EventType methods
      responses:
        "200":
          $ref: "#/components/responses/GetEventTypesOK"
        "500":
          $ref: "#/components/responses/ResponseInternalServerError"

    post:
      summary: Register one or more event types
      description: |
        Register one or more new event types with the message bus.
      operationId: RegisterEventTypes
      tags:
        - EventType methods
      requestBody:
        $ref: "#/components/requestBodies/RegisterEventTypes"
      responses:
        "200":
          $ref: "#/components/responses/ResponseOK"
        "400":
          $ref: "#/components/responses/ResponseBadRequest"
        "409":
          $ref: "#/components/responses/ResponseConflict"

  /event_type/{source_id}:
    get:
      summary: Get event types by source ID
      description: |
        Get all event types that are registered with the message bus for a specific source ID.
      operationId: getEventTypesBySourceID
      tags:
        - EventType methods
      parameters:
        - $ref: "#/components/parameters/SourceID"
      responses:
        "200":
          $ref: "#/components/responses/GetEventTypesOK"
        "404":
          $ref: "#/components/responses/ResponseNotFound"

  /event_type/{source_id}/{name}:
    get:
      summary: Get an event type by source ID and name
      description: |
        Get an event type that is registered with the message bus for a specific source ID and event name.
      operationId: getEventType
      tags:
        - EventType methods
      parameters:
        - $ref: "#/components/parameters/SourceID"
        - $ref: "#/components/parameters/EventName"
      responses:
        "200":
          $ref: "#/components/responses/GetEventTypeOK"
        "404":
          $ref: "#/components/responses/ResponseNotFound"

  /event/{source_id}/{name}:
    post:
      summary: Publish an event
      description: |
        Publish an event to the message bus.
      operationId: publishEvent
      tags:
        - Event methods
      parameters:
        - $ref: "#/components/parameters/SourceID"
        - $ref: "#/components/parameters/EventName"
      requestBody:
        $ref: "#/components/requestBodies/PublishEvent"
      responses:
        "200":
          $ref: "#/components/responses/PublishEventOK"
        "400":
          $ref: "#/components/responses/ResponseBadRequest"
        "404":
          $ref: "#/components/responses/ResponseNotFound"

  /event/{source_id}:
    get:
      summary: Subscribe to events by source ID (WebSocket)
      description: |
        Subscribe to event by `source_id` via WebSocket.

        > `names` can be specified in the query string to subscribe to specific event types.
      operationId: subscribeEventWS
      tags:
        - WebSocket Endpoints
      parameters:
        - $ref: "#/components/parameters/SourceID"
        - $ref: "#/components/parameters/EventNames"
      responses:
        "101":
          description: |
            The connection will be upgraded to a WebSocket connection and the client will receive events as they are published.

  /action_type:
    get:
      summary: List action types
      description: |
        List all action types that are currently registered with the message bus.
      operationId: getActionTypes
      tags:
        - ActionType methods
      responses:
        "200":
          $ref: "#/components/responses/GetActionTypesOK"

    post:
      summary: Register one or more action types
      description: |
        Register one or more new action types with the message bus.
      operationId: RegisterActionTypes
      tags:
        - ActionType methods
      requestBody:
        $ref: "#/components/requestBodies/RegisterActionTypes"
      responses:
        "200":
          $ref: "#/components/responses/ResponseOK"
        "400":
          $ref: "#/components/responses/ResponseBadRequest"
        "409":
          $ref: "#/components/responses/ResponseConflict"

  /action_type/{source_id}:
    get:
      summary: Get action types by source ID
      description: |
        Get all action types that are registered with the message bus for a specific source ID.
      operationId: getActionTypesBySourceID
      tags:
        - ActionType methods
      parameters:
        - $ref: "#/components/parameters/SourceID"
      responses:
        "200":
          $ref: "#/components/responses/GetActionTypesOK"
        "404":
          $ref: "#/components/responses/ResponseNotFound"

  /action_type/{source_id}/{name}:
    get:
      summary: Get an action type by source ID and name
      description: |
        Get an action type that is registered with the message bus for a specific source ID and action name.
      operationId: getActionType
      tags:
        - ActionType methods
      parameters:
        - $ref: "#/components/parameters/SourceID"
        - $ref: "#/components/parameters/ActionName"
      responses:
        "200":
          $ref: "#/components/responses/GetActionTypeOK"
        "404":
          $ref: "#/components/responses/ResponseNotFound"

  /action/{source_id}/{name}:
    post:
      summary: Trigger an action
      description: |
        Trigger an action on the message bus.
      operationId: triggerAction
      tags:
        - Action methods
      parameters:
        - $ref: "#/components/parameters/SourceID"
        - $ref: "#/components/parameters/ActionName"
      requestBody:
        $ref: "#/components/requestBodies/TriggerAction"
      responses:
        "200":
          $ref: "#/components/responses/TriggerActionOK"
        "400":
          $ref: "#/components/responses/ResponseBadRequest"
        "404":
          $ref: "#/components/responses/ResponseNotFound"

  /action/{source_id}:
    get:
      summary: Subscribe to actions by source ID (WebSocket)
      description: |
        Subscribe to actions by `source_id` via WebSocket.

        > `names` can be specified in the query string to subscribe to specific action types.
      operationId: subscribeActionWS
      tags:
        - WebSocket Endpoints
      parameters:
        - $ref: "#/components/parameters/SourceID"
        - $ref: "#/components/parameters/ActionNames"
      responses:
        "101":
          description: |
            The connection will be upgraded to a WebSocket connection and the client will receive actions as they are triggered.

  /socket.io:
    get:
      summary: Subscribe to events and actions (SocketIO)
      description: |
        Subscribe to events and actions via SocketIO.

        - SocketIO `room` should be either `event` or `action`

      operationId: subscribeSIO
      tags:
        - SocketIO Endpoints
      responses:
        "101":
          description: |
            The connection will be upgraded to a SocketIO connection and the client will receive events as they are published.
        "200":
          description: |
            Polling initialized for SocketIO

    post:
      summary: Poll events and actions (SocketIO)
      description: |
        Poll events and actions by via SocketIO.
      operationId: pollSIO
      tags:
        - SocketIO Endpoints
      responses:
        "200":
          description: |
            Polling continued from SocketIO

  /socket.io/:
    get:
      summary: Subscribe to events and actions (SocketIO)
      description: |
        > Same as `/socket.io` except it comes with a trailing slash `/` - a workaround to maximize compatibility
      operationId: subscribeSIO2
      responses:
        "101":
          description: |
            The connection will be upgraded to a SocketIO connection and the client will receive events as they are published.
        "200":
          description: |
            Polling initialized for SocketIO

    post:
      summary: Poll events and actions (SocketIO)
      description: |
        > Same as `/socket.io` except it comes with a trailing slash `/` - a workaround to maximize compatibility
      operationId: pollSIO2
      responses:
        "200":
          description: |
            Polling continued from SocketIO

components:
  securitySchemes:
    access_token:
      type: apiKey
      in: header
      name: Authorization

  parameters:
    SourceID:
      name: source_id
      in: path
      required: true
      schema:
        type: string
        example: "local-storage"

    EventName:
      name: name
      in: path
      required: true
      schema:
        type: string
        example: "local-storage:disk:added"

    EventNames:
      name: names
      in: query
      allowEmptyValue: false
      required: false
      schema:
        type: array
        items:
          type: string
      example: "local-storage:disk:added,local-storage:disk:removed"

    ActionName:
      name: name
      in: path
      required: true
      schema:
        type: string
        example: "local-storage:partition:format"

    ActionNames:
      name: names
      in: query
      allowEmptyValue: false
      required: false
      schema:
        type: array
        items:
          type: string
      example: "local-storage:partition:format,local-storage:partition:mount"

  requestBodies:
    RegisterEventTypes:
      description: (TODO)
      required: true
      content:
        application/json:
          schema:
            type: array
            items:
              $ref: "#/components/schemas/EventType"

    PublishEvent:
      description: (TODO)
      required: true
      content:
        application/json:
          schema:
            type: object
            description: event properties
            additionalProperties:
              type: string
            example:
              local-storage:vendor: SanDisk
              local-storage:model: Cruzer
              local-storage:uuid: 442e0e5b-9d3e-4fe8-b46f-9c4141fdecd7

    RegisterActionTypes:
      description: (TODO)
      required: true
      content:
        application/json:
          schema:
            type: array
            items:
              $ref: "#/components/schemas/ActionType"

    TriggerAction:
      description: (TODO)
      required: true
      content:
        application/json:
          schema:
            type: object
            description: action properties
            additionalProperties:
              type: string
            example:
              local-storage:uuid: 442e0e5b-9d3e-4fe8-b46f-9c4141fdecd7

  responses:
    ResponseOK:
      description: OK
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/BaseResponse"

    ResponseInternalServerError:
      description: (TODO)
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/BaseResponse"

    ResponseNotFound:
      description: Not Found
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/BaseResponse"
          example:
            message: "Not Found"

    ResponseBadRequest:
      description: Bad Request
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/BaseResponse"
          example:
            message: "Bad Request"

    ResponseConflict:
      description: Conflict
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/BaseResponse"
          example:
            message: "Conflict"

    GetEventTypesOK:
      description: OK
      content:
        application/json:
          schema:
            type: array
            items:
              $ref: "#/components/schemas/EventType"

    GetEventTypeOK:
      description: OK
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/EventType"

    PublishEventOK:
      description: OK
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Event"

    GetActionTypesOK:
      description: OK
      content:
        application/json:
          schema:
            type: array
            items:
              $ref: "#/components/schemas/ActionType"

    GetActionTypeOK:
      description: OK
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ActionType"

    TriggerActionOK:
      description: OK
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Action"

  schemas:
    BaseResponse:
      properties:
        message:
          readOnly: true
          description: message returned by server side if there is any
          type: string
          example: ""

    PropertyType:
      type: object
      required:
        - "name"
      properties:
        name:
          type: string
          description: |-
            property name

            > It is recommended for a property name to be as descriptive as possible. One option is to prefix with a namespace.
            > - If the property is source specific, prefix with source ID. For example, `local-storage:vendor`
            > - Otherwise, prefix with `common:`. For example, `common:email`
            >
            > Some bad examples are `id`, `avail`, `blk`...which can be ambiguous and confusing.
          example: "local-storage:vendor"
        description:
          type: string
          example: "Hardware vendor of this storage"
        example:
          type: string
          example: "SanDisk"

    EventType:
      type: object
      required:
        - "sourceID"
        - "name"
        - "propertyTypeList"
      properties:
        sourceID:
          type: string
          description: event source id to identify where the event comes from
          example: "local-storage"
        name:
          type: string
          description: |-
            event name

            (there is no naming convention for event names, but it is recommended to name each as structural and descriptive as possible)
          example: "local-storage:disk:added"
        propertyTypeList:
          type: array
          items:
            $ref: "#/components/schemas/PropertyType"

    Event:
      type: object
      required:
        - "sourceID"
        - "name"
        - "properties"
      properties:
        sourceID:
          type: string
          description: associated source id
          example: "local-storage"
        name:
          type: string
          description: event name
          example: "local-storage:disk:added"
        uuid:
          type: string
          description: event uuid
          example: "442e0e5b-9d3e-4fe8-b46f-9c4141fdecd7"
        properties:
          type: object
          description: event properties
          additionalProperties:
            type: string
          example:
            local-storage:vendor: SanDisk
            local-storage:model: Cruzer
            local-storage:uuid: 442e0e5b-9d3e-4fe8-b46f-9c4141fdecd7
        timestamp:
          type: string
          description: timestamp this event took place
          format: date-time

    ActionType:
      type: object
      required:
        - "sourceID"
        - "name"
        - "propertyTypeList"
      properties:
        sourceID:
          type: string
          description: action source id to identify where the action will take
          example: "local-storage"
        name:
          type: string
          description: |-
            action name

            (there is no naming convention for action names, but it is recommended to name each as structural and descriptive as possible)
          example: "local-storage:disk:format"
        propertyTypeList:
          type: array
          items:
            $ref: "#/components/schemas/PropertyType"

    Action:
      type: object
      required:
        - "sourceID"
        - "name"
        - "properties"
      properties:
        sourceID:
          type: string
          description: associated source id
          example: "local-storage"
        name:
          type: string
          description: action name
          example: "local-storage:disk:format"
        properties:
          type: object
          description: event properties
          additionalProperties:
            type: string
          example:
            local-storage:vendor: SanDisk
            local-storage:model: Cruzer
            local-storage:uuid: 442e0e5b-9d3e-4fe8-b46f-9c4141fdecd7
        timestamp:
          type: string
          description: timestamp this action took place
          format: date-time