openapi: 3.1.0
info:
  title: JSupervisor REST API
  description: |
    JSupervisor is a process management and monitoring service that provides
    comprehensive control over application processes. This API enables you to:

    - Start, stop, and restart processes individually or in bulk
    - Monitor process status and health
    - Retrieve process logs and statistics
    - Configure process behavior and auto-start settings

    The API follows RESTful principles and returns JSON responses.
  contact:
    name: Alex Mondshain
    url: https://www.alexmond.org/jsupervisor/current/
    email: alex.mondshain@gmail.com
  license:
    name: Apache License 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.txt
  version: 0.0.2
servers:
- url: http://localhost:8086
  description: Local Development Server
tags:
- name: Supervisor Information
  description: APIs for supervisor system information and monitoring
- name: Event Management
  description: Operations for managing and querying process event history
- name: Group Process Operations
  description: APIs for managing multiple processes simultaneously
- name: Process Management
  description: APIs for managing individual processes
paths:
  /api/v1/processes/stop/{name}:
    post:
      tags:
      - Process Management
      summary: Stop process
      description: Stop a specific process
      operationId: stopProcess
      parameters:
      - name: name
        in: path
        description: Process name
        required: true
        schema:
          type: string
      responses:
        "400":
          description: Business error
          content:
            '*/*':
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "500":
          description: Failed to stop process
          content:
            '*/*':
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "200":
          description: Process stop initiated successfully
        "404":
          description: Process not found
  /api/v1/processes/start/{name}:
    post:
      tags:
      - Process Management
      summary: Start process
      description: Start a specific process
      operationId: startProcess
      parameters:
      - name: name
        in: path
        description: Process name
        required: true
        schema:
          type: string
      responses:
        "400":
          description: Invalid process configuration
          content:
            '*/*':
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "500":
          description: Failed to start process
          content:
            '*/*':
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "200":
          description: Process start initiated successfully
          content:
            '*/*':
              schema:
                $ref: "#/components/schemas/ResponseMessage"
  /api/v1/processes/restart/{name}:
    post:
      tags:
      - Process Management
      summary: Restart process
      description: Restart a specific process
      operationId: restartProcess
      parameters:
      - name: name
        in: path
        description: Process name
        required: true
        schema:
          type: string
      responses:
        "400":
          description: Business error
          content:
            '*/*':
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "500":
          description: Failed to restart process
          content:
            '*/*':
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "200":
          description: Process restart initiated successfully
        "404":
          description: Process not found
  /api/v1/processes/group/stop:
    post:
      tags:
      - Group Process Operations
      summary: Stop all processes
      description: Stop all currently running processes
      operationId: stopAll
      responses:
        "400":
          description: Business error
          content:
            '*/*':
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "500":
          description: Error occurred while stopping processes
          content:
            '*/*':
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "200":
          description: All processes stopped successfully
        "404":
          description: No running processes found
  /api/v1/processes/group/start:
    post:
      tags:
      - Group Process Operations
      summary: Start all processes
      description: Start all configured processes that are not currently running
      operationId: startAll
      responses:
        "400":
          description: Business error
          content:
            '*/*':
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "500":
          description: Error occurred while starting processes
          content:
            '*/*':
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "200":
          description: All processes started successfully
        "409":
          description: Some processes are already running
  /api/v1/processes/group/restart:
    post:
      tags:
      - Group Process Operations
      summary: Restart all processes
      description: Restart all configured processes
      operationId: restartAll
      responses:
        "400":
          description: Business error
          content:
            '*/*':
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "500":
          description: Error occurred while restarting processes
          content:
            '*/*':
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "200":
          description: All processes restarted successfully
  /api/v1/supervisor/info:
    get:
      tags:
      - Supervisor Information
      summary: Get supervisor info
      description: Retrieve basic supervisor information
      operationId: getSupervisorInfo
      responses:
        "400":
          description: Business error
          content:
            '*/*':
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "500":
          description: Internal server error
          content:
            '*/*':
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "200":
          description: OK
          content:
            '*/*':
              schema:
                $ref: "#/components/schemas/SupervisorInfo"
  /api/v1/processes:
    get:
      tags:
      - Process Management
      summary: List all processes
      description: Retrieve status information for all configured processes
      operationId: getAllProcessesInfo
      responses:
        "400":
          description: Business error
          content:
            '*/*':
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "500":
          description: Internal server error
          content:
            '*/*':
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "200":
          description: Successfully retrieved list of processes
          content:
            '*/*':
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/ProcessStatusInfo"
  /api/v1/processes/info/{name}:
    get:
      tags:
      - Process Management
      summary: Get process status
      description: Get the current status of a specific process
      operationId: getProcessStatus
      parameters:
      - name: name
        in: path
        description: Process name
        required: true
        schema:
          type: string
      responses:
        "400":
          description: Business error
          content:
            '*/*':
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "500":
          description: Failed to retrieve process status
          content:
            '*/*':
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "200":
          description: Successfully retrieved process status
          content:
            '*/*':
              schema:
                $ref: "#/components/schemas/ProcessStatusInfo"
        "404":
          description: Process not found
          content:
            '*/*':
              schema:
                $ref: "#/components/schemas/ProcessStatusInfo"
  /api/v1/events:
    get:
      tags:
      - Event Management
      summary: Get paginated events
      description: Retrieves a paginated list of all process events with customizable
        sorting
      operationId: getEvents
      parameters:
      - name: page
        in: query
        description: Page number (0-based)
        required: false
        schema:
          type: integer
          minimum: 0
        example: 0
      - name: size
        in: query
        description: Number of items per page
        required: false
        schema:
          type: integer
          maximum: 100
          minimum: 1
        example: 20
      - name: sortBy
        in: query
        description: Field to sort by
        required: false
        schema:
          type: string
          enum:
          - eventTime
          - processName
          - newStatus
          - oldStatus
          - pid
        example: eventTime
      - name: sortDirection
        in: query
        description: Sort direction
        required: false
        schema:
          type: string
          enum:
          - asc
          - desc
        example: desc
      responses:
        "400":
          description: Invalid pagination or sorting parameters
        "500":
          description: Internal server error
          content:
            '*/*':
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "200":
          description: Successfully retrieved events
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Page"
  /api/v1/events/{id}:
    get:
      tags:
      - Event Management
      summary: Get event by ID
      description: Retrieves detailed information about a specific process event
      operationId: getEventById
      parameters:
      - name: id
        in: path
        description: Event ID
        required: true
        schema:
          type: integer
          format: int64
        example: 123
      responses:
        "400":
          description: Business error
          content:
            '*/*':
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "500":
          description: Internal server error
          content:
            '*/*':
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "200":
          description: Event found
          content:
            '*/*':
              schema:
                $ref: "#/components/schemas/ProcessEventEntry"
        "404":
          description: Event not found
          content:
            '*/*':
              schema:
                $ref: "#/components/schemas/ProcessEventEntry"
  /api/v1/events/count:
    get:
      tags:
      - Event Management
      summary: Get total event count
      description: Returns the total number of events in the system
      operationId: getTotalEventsCount
      responses:
        "400":
          description: Business error
          content:
            '*/*':
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "500":
          description: Internal server error
          content:
            '*/*':
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "200":
          description: Successfully retrieved count
          content:
            '*/*':
              schema:
                type: object
                additionalProperties:
                  type: integer
                  format: int64
  /api/v1/events/by-status/{status}:
    get:
      tags:
      - Event Management
      summary: Get events by status
      description: Retrieves paginated events matching a specific process status
      operationId: getEventsByStatus
      parameters:
      - name: status
        in: path
        description: Process status to filter by
        required: true
        schema:
          type: string
          enum:
          - not_started
          - running
          - finished
          - unknown
          - failed
          - failed_to_start
          - stopped
          - stopping
          - aborted
          - starting
          - healthy
          - unhealthy
        example: running
      - name: page
        in: query
        description: Page number (0-based)
        required: false
        schema:
          type: integer
          format: int32
          default: 0
        example: 0
      - name: size
        in: query
        description: Number of items per page
        required: false
        schema:
          type: integer
          format: int32
          default: 20
        example: 20
      - name: sortBy
        in: query
        description: Field to sort by
        required: false
        schema:
          type: string
          default: eventTime
        example: eventTime
      - name: sortDirection
        in: query
        description: Sort direction
        required: false
        schema:
          type: string
          default: desc
        example: desc
      responses:
        "400":
          description: Invalid status value
        "500":
          description: Internal server error
          content:
            '*/*':
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "200":
          description: Successfully retrieved events
          content:
            '*/*':
              schema:
                $ref: "#/components/schemas/PageProcessEventEntry"
  /api/v1/events/by-process/{processName}:
    get:
      tags:
      - Event Management
      summary: Get events by process name
      description: Retrieves paginated events for a specific process
      operationId: getEventsByProcess
      parameters:
      - name: processName
        in: path
        description: Process name
        required: true
        schema:
          type: string
        example: myapp
      - name: page
        in: query
        description: Page number (0-based)
        required: false
        schema:
          type: integer
          format: int32
          default: 0
        example: 0
      - name: size
        in: query
        description: Number of items per page
        required: false
        schema:
          type: integer
          format: int32
          default: 20
        example: 20
      - name: sortBy
        in: query
        description: Field to sort by
        required: false
        schema:
          type: string
          default: eventTime
        example: eventTime
      - name: sortDirection
        in: query
        description: Sort direction
        required: false
        schema:
          type: string
          default: desc
        example: desc
      responses:
        "400":
          description: Business error
          content:
            '*/*':
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "500":
          description: Internal server error
          content:
            '*/*':
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "200":
          description: Successfully retrieved events
          content:
            '*/*':
              schema:
                $ref: "#/components/schemas/PageProcessEventEntry"
        "404":
          description: Process not found
          content:
            '*/*':
              schema:
                $ref: "#/components/schemas/PageProcessEventEntry"
components:
  schemas:
    ErrorResponse:
      type: object
      description: Standard error response for REST APIs.
      properties:
        timestamp:
          type: string
          format: date-time
          description: Timestamp when the error occurred
          example: 2025-11-17T10:15:30Z
        path:
          type: string
          description: Request path where the error occurred
          example: /api/v1/processes
        error:
          type: string
          description: Short error identifier
          example: BAD_REQUEST
        message:
          type: string
          description: Human readable error message
          example: Invalid process ID
        code:
          type: string
          description: Optional application-specific error code
          example: JSUPERVISOR-001
    ResponseMessage:
      type: object
      properties:
        message:
          type: string
        error:
          type: string
    SupervisorInfo:
      type: object
      description: Supervisor system information including hardware and OS details
      properties:
        nodeName:
          type: string
          description: The name of the node in the supervisor system
          example: supervisor-1
        description:
          type: string
          description: Description of the node
          example: Main supervisor node
        physicalMemory:
          type: string
          description: Total physical memory available in the system
          example: 16
        physicalCpu:
          type: integer
          format: int32
          description: Number of physical CPU cores
          example: 8
        operatingSystem:
          type: string
          description: Operating system information
          example: Windows 10 Pro
        availableMemory:
          type: string
          description: Currently available memory in the system
          example: 8.5
    ProcessStatusInfo:
      type: object
      description: Represents process status information
      properties:
        name:
          type: string
          description: Name of the process
          example: myapp
        status:
          type: string
          description: "Current status of the process (e.g., running, stopped, failed)"
          enum:
          - not_started
          - running
          - finished
          - unknown
          - failed
          - failed_to_start
          - stopped
          - stopping
          - aborted
          - starting
          - healthy
          - unhealthy
        pid:
          type: integer
          format: int64
          description: Process ID assigned by the operating system
          example: 1234
        startTime:
          type: string
          format: date-time
          description: Timestamp when the process was started
        endTime:
          type: string
          format: date-time
          description: Timestamp when the process ended
        exitCode:
          type: integer
          format: int32
          description: Process exit code
          example: 0
        processRuntime:
          type: string
          format: duration
          description: Process runtime duration
        processUptime:
          type: string
          description: Formatted process uptime
          example: 2d 5h 30m
        stdoutLogfile:
          type: string
          description: "File path where the standard output (stdout) of the process\
            \ will be logged. If not specified, stdout will be inherited from the\
            \ parent process."
        stderrLogfile:
          type: string
          description: "File path where the standard error (stderr) of the process\
            \ will be logged. If not specified, stderr will be inherited from the\
            \ parent process."
        failedErrorLog:
          type: string
          description: Error log content when process failed to start
    Page:
      type: object
      properties:
        totalPages:
          type: integer
          format: int32
        totalElements:
          type: integer
          format: int64
        first:
          type: boolean
        last:
          type: boolean
        pageable:
          $ref: "#/components/schemas/PageableObject"
        numberOfElements:
          type: integer
          format: int32
        size:
          type: integer
          format: int32
        content:
          type: array
          items: {}
        number:
          type: integer
          format: int32
        sort:
          $ref: "#/components/schemas/SortObject"
        empty:
          type: boolean
    PageableObject:
      type: object
      properties:
        pageSize:
          type: integer
          format: int32
        paged:
          type: boolean
        unpaged:
          type: boolean
        pageNumber:
          type: integer
          format: int32
        offset:
          type: integer
          format: int64
        sort:
          $ref: "#/components/schemas/SortObject"
    SortObject:
      type: object
      properties:
        unsorted:
          type: boolean
        sorted:
          type: boolean
        empty:
          type: boolean
    ProcessEventEntry:
      type: object
      description: Represents an event entry for process state changes and lifecycle
        events
      properties:
        id:
          type: integer
          format: int64
          description: Unique identifier for the process event
          example: 1
        pid:
          type: integer
          format: int64
          description: Process ID of the running process
          example: 12345
        eventTime:
          type: string
          format: date-time
          description: Timestamp when the event occurred
          example: 2025-11-17T10:30:00
        processName:
          type: string
          description: Name of the managed process
          example: my-application
        startTime:
          type: string
          format: date-time
          description: Timestamp when the process was started
          example: 2025-11-17T10:00:00
        endTime:
          type: string
          format: date-time
          description: "Timestamp when the process ended, null if still running"
          example: 2025-11-17T10:15:00
        exitCode:
          type: integer
          format: int32
          description: "Exit code of the process, null if still running"
          example: 0
        newStatus:
          type: string
          description: New status of the process after the event
          enum:
          - not_started
          - running
          - finished
          - unknown
          - failed
          - failed_to_start
          - stopped
          - stopping
          - aborted
          - starting
          - healthy
          - unhealthy
        oldStatus:
          type: string
          description: Previous status of the process before the event
          enum:
          - not_started
          - running
          - finished
          - unknown
          - failed
          - failed_to_start
          - stopped
          - stopping
          - aborted
          - starting
          - healthy
          - unhealthy
        processUptime:
          type: string
          description: Duration for which the process has been running
          example: PT15M
    PageProcessEventEntry:
      type: object
      properties:
        totalPages:
          type: integer
          format: int32
        totalElements:
          type: integer
          format: int64
        first:
          type: boolean
        last:
          type: boolean
        pageable:
          $ref: "#/components/schemas/PageableObject"
        numberOfElements:
          type: integer
          format: int32
        size:
          type: integer
          format: int32
        content:
          type: array
          items:
            $ref: "#/components/schemas/ProcessEventEntry"
        number:
          type: integer
          format: int32
        sort:
          $ref: "#/components/schemas/SortObject"
        empty:
          type: boolean