adaptorex/doc/api/public/asyncapi.yaml

Connect all your live interactive storytelling devices and software

asyncapi: 2.0.0
info:
  title: adaptor:ex frontend socket API
  description: subscribe and publish to message streams about user interactions, data changes and the live session status
  version: 0.0.1
servers:
  custom:
    url: "ws://{domain}:{port}"
    protocol: ws
    description: Custom server
    security:
      - basicAuth: []
    variables:
      domain:
        default: "localhost"
      port:
        default: "8080"
channels:
  /:
    subscribe:
      summary: Changes in adaptor root
      message:
        oneOf:
          - name: games
            description: Game has been removed or added.
            payload:
              type: array
              description: List of current games.
              items:
                $ref: "openapi.yaml#/components/schemas/game_preview"
  /log/{level}:
    parameters:
      level:
        $ref: "#/components/parameters/log_level"
    subscribe:
      summary: Get console log messages
      message:
        name: log
        payload:
          type: array
          items:
            type: object
            properties:
              id:
                type: integer
              level:
                type: string
                enum: [error, warn, info, debug, trace]
              topic:
                type: string
              message:
                type: string
  /game/{game}:
    parameters:
      game:
        $ref: "#/components/parameters/game"
    subscribe:
      summary: Get updates on changes to game architecture
      message:
        oneOf:
          - name: level
            description: Level has been removed or added.
            payload:
              type: array
              description: Updated list of levels
              items:
                $ref: "openapi.yaml#/components/schemas/level_preview"
          - name: plugin
            description: A plugin was added to or removed from the game.
            payload:
              type: array
              description: Updated list of active plugins.
              items:
                $ref: "openapi.yaml#/components/schemas/plugin_preview"
          - name: actions
            description: Actions for this game have changed because a plugin was added or removed.
            payload:
              type: array
              items:
                $ref: "openapi.yaml#/components/schemas/action_schema"
          - name: action_schema_update
            description: an action payload schema changed.
            payload:
              $ref: "openapi.yaml#/components/schemas/action"
          - name: media
            description: Media files were added or removed.
            deprecated: true
            payload:
              type: array
              items:
                type: string
          - name: files
            description: Files were changed, added or removed in the data directory.
            payload:
              type: array
              items:
                $ref: "openapi.yaml#/components/schemas/file"
  /game/{game}/live/sessions:
    parameters:
      game:
        $ref: "#/components/parameters/game"
    subscribe:
      summary: Get updates on changes in running sessions
      message:
        oneOf:
          - name: changed
            description: Status of updated sessions. Is published on launched sessions and state changes in a session.
            payload:
              type: array
              description: List of updated sessions.
              items:
                $ref: "openapi.yaml#/components/schemas/session"
          - name: removed
            description: A session was canceled. List of _id properties of removed sessions.
            payload:
              description: List of session ids of removed sessions.
              type: array
              items:
                type: string
  /game/{game}/live/items:
    parameters:
      game:
        $ref: "#/components/parameters/game"
    subscribe:
      summary: Get updates on plugin and data items
      description: Whenever a new item appears, changes or is removed, information is published. On socket namespace connect latest changed documents are published in order of change.
      message:
        oneOf:
          - name: changed
            description: A Data or Plugin Item has changed or was added
            payload:
              type: array
              items:
                $ref: "openapi.yaml#/components/schemas/item"
          - name: removed
            description: A Data or Plugin Item was removed. List of _id properties of removed items.
            payload:
              type: array
              items:
                type: string
                description: item _id property
  /game/{game}/level/{level}:
    parameters:
      game:
        $ref: "#/components/parameters/game"
      level:
        $ref: "#/components/parameters/level"
    subscribe:
      summary: Get updates on changes to the level file
      message:
        oneOf:
          - name: variables
            description: Updated level variables and functions
            payload:
              type: object
          - name: revision_restored
          - description: A revision was restored. There might be changes anywhere in the level document.
            payload:
              $ref: "openapi.yaml#/components/schemas/level"
          - name: state_update
            payload:
              $ref: "openapi.yaml#/components/schemas/states"
          - name: state_deleted
            payload:
              type: object
              properties:
                id:
                  type: string
                  description: state id
          - name: path_update
            description: >
              Changes in states might require an adjustment of several states paths.
              path_update will always serve paths for all states in the respective level, 
              according to the level and states structure but only the path elements themselves. 
              Make sure to merge the states `path` properties from path_update payload and not overwrite the level or state.
            payload:
              $ref: "openapi.yaml#/components/schemas/path_update"
          - name: user_joined
            description: another user or browser window is now also editing this level
            payload:
              $ref: "#/components/schemas/user_session"
          - name: user_left
            description: another user or browser window stopped editing this level
            payload:
              $ref: "#/components/schemas/user_session"
          - name: state_busy
            description: some state is being edited by another user session
            payload:
              type: object
              properties:
                state:
                  type: string
                  description: state id
                user_session:
                  $ref: "#/components/schemas/user_session"
          - name: state_clear
            description: state is not longer being edited by another user session.
            payload:
              type: string
              description: state id
          - name: user_interaction
            description: Interactions from other user sessions that are editing this level. What goes in "pubish user_interaction" is broadcasted to "subscribe user_interaction"
            payload:
              type: object
              properties:
                user_session:
                  $ref: "#/components/schemas/user_session"
                payload: {}
    publish:
      summary: Report changes and interactions inside the level context
      message:
        oneOf:
          - name: enter_state
            description: mark a state as busy when beginning to edit it. If its busy already user session will enter queue of state editors. Automatically clears any other state the user session is in.
            payload:
              type: string
              description: state id
          - name: leave_state
            description: clear state so other user sessions can edit it.
            payload:
              # actually here nothing needs to come. Socket ID comes with the header I think
              type: string
          - name: user_interaction
            description: Report interactions that can be subscribed to by other user sessions. What goes in "pubish user_interaction" is broadcasted to "subscribe user_interaction"
            payload: {}
components:
  parameters:
    game:
      description: game name
      schema:
        $ref: "openapi.yaml#/components/parameters/game/schema"
    level:
      description: level _id or name property
      schema:
        $ref: "openapi.yaml#/components/parameters/level/schema"
    session:
      description: session _id or name property
      schema:
        $ref: "openapi.yaml#/components/parameters/session/schema"
    log_level:
      description: get log messages for this and more urgent levels. error highest, trace is lowest urgency.
      schema:
        type: string
        enum: ["error", "warn", "info", "debug", "trace"]
  schemas:
    user_session:
      type: object
      properties:
        socket:
          type: string
          description: user socket session id
        user:
          type: string
          description: user login property
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic