openapi: 3.0.3
info:
  title: SPORE Embedded System API
  description: |
    RESTful API for monitoring and controlling the SPORE embedded system.
    
    The SPORE system provides comprehensive task management, system monitoring,
    and cluster management capabilities for ESP8266-based embedded devices.
    
    ## Features
    - **Task Management**: Monitor and control background tasks
    - **System Monitoring**: Real-time system resource tracking
    - **Cluster Management**: Multi-node cluster coordination
    - **OTA Updates**: Over-the-air firmware updates
    - **Health Monitoring**: System and task health metrics
    
    ## Authentication
    Currently, no authentication is required. All endpoints are accessible
    from the local network.
    
    ## Rate Limiting
    No rate limiting is currently implemented. Use responsibly.
    
    ## Base URL
    The API is accessible at `http://{device-ip}/` where `{device-ip}` is
    the IP address of your SPORE device on the local network.
  
  version: 1.0.0
  contact:
    name: SPORE Development Team
    url: https://git.dcentral.systems/iot/spore
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT

servers:
  - url: http://{device-ip}
    description: Local SPORE device
    variables:
      device-ip:
        description: IP address of your SPORE device
        default: "10.0.1.60"

paths:
  /api/tasks/status:
    get:
      summary: Get comprehensive task status
      description: |
        Returns detailed status information for all registered tasks,
        including system resource metrics and task execution details.
        
        This endpoint provides a complete overview of the system's
        task management status and can be used for monitoring and
        debugging purposes.
      
      tags:
        - Task Management
      
      responses:
        '200':
          description: Task status retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TaskStatusResponse'
              examples:
                default:
                  summary: Default response
                  value:
                    summary:
                      totalTasks: 6
                      activeTasks: 5
                    tasks:
                      - name: "discovery_send"
                        interval: 1000
                        enabled: true
                        running: true
                        autoStart: true
                      - name: "heartbeat"
                        interval: 2000
                        enabled: true
                        running: true
                        autoStart: true
                      - name: "status_update"
                        interval: 1000
                        enabled: true
                        running: true
                        autoStart: true
                    system:
                      freeHeap: 48748
                      uptime: 12345
        
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/tasks/control:
    post:
      summary: Control individual task operations
      description: |
        Controls the execution state of individual tasks. Supports
        enabling, disabling, starting, stopping, and getting detailed
        status for specific tasks.
        
        This endpoint is useful for dynamic task management without
        requiring system restarts.
      
      tags:
        - Task Management
      
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required:
                - task
                - action
              properties:
                task:
                  type: string
                  description: Name of the task to control
                  example: "heartbeat"
                action:
                  type: string
                  description: Action to perform on the task
                  enum: [enable, disable, start, stop, status]
                  example: "disable"
      
      responses:
        '200':
          description: Task operation completed successfully
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/TaskControlResponse'
                  - $ref: '#/components/schemas/TaskStatusDetailResponse'
              examples:
                enable:
                  summary: Task enabled
                  value:
                    success: true
                    message: "Task enabled"
                    task: "heartbeat"
                    action: "enable"
                status:
                  summary: Task status retrieved
                  value:
                    success: true
                    message: "Task status retrieved"
                    task: "discovery_send"
                    action: "status"
                    taskDetails:
                      name: "discovery_send"
                      enabled: true
                      running: true
                      interval: 1000
                      system:
                        freeHeap: 48748
                        uptime: 12345
        
        '400':
          description: Bad request - invalid parameters or action
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                missing_params:
                  summary: Missing required parameters
                  value:
                    success: false
                    message: "Missing parameters. Required: task, action"
                    example: "{\"task\": \"discovery_send\", \"action\": \"status\"}"
                invalid_action:
                  summary: Invalid action specified
                  value:
                    success: false
                    message: "Invalid action. Use: enable, disable, start, stop, or status"
                    task: "heartbeat"
                    action: "invalid_action"

  /api/node/status:
    get:
      summary: Get system status and API information
      description: |
        Returns comprehensive system resource information including
        memory usage, chip details, and a registry of all available
        API endpoints.
      
      tags:
        - System Status
      
      responses:
        '200':
          description: System status retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SystemStatusResponse'
              examples:
                default:
                  summary: Default response
                  value:
                    freeHeap: 48748
                    chipId: 12345678
                    sdkVersion: "3.1.2"
                    cpuFreqMHz: 80
                    flashChipSize: 1048576
                    api:
                      - uri: "/api/node/status"
                        method: 1
                      - uri: "/api/tasks/status"
                        method: 1
                      - uri: "/api/tasks/control"
                        method: 3

  /api/cluster/members:
    get:
      summary: Get cluster membership information
      description: |
        Returns information about all nodes in the cluster,
        including their health status, resources, and API endpoints.
      
      tags:
        - Cluster Management
      
      responses:
        '200':
          description: Cluster information retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClusterMembersResponse'
              examples:
                default:
                  summary: Default response
                  value:
                    members:
                      - hostname: "spore-node-1"
                        ip: "192.168.1.100"
                        lastSeen: 1234567890
                        latency: 5
                        status: "ACTIVE"
                        resources:
                          freeHeap: 48748
                          chipId: 12345678
                          sdkVersion: "3.1.2"
                          cpuFreqMHz: 80
                          flashChipSize: 1048576
                        api:
                          - uri: "/api/node/status"
                            method: "GET"
                          - uri: "/api/tasks/status"
                            method: "GET"

  /api/node/update:
    post:
      summary: Handle firmware update via OTA
      description: |
        Initiates an over-the-air firmware update. The firmware
        file should be uploaded as multipart/form-data.
      
      tags:
        - System Management
      
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                firmware:
                  type: string
                  format: binary
                  description: Firmware binary file (.bin)
      
      responses:
        '200':
          description: Firmware update initiated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpdateResponse'
              examples:
                default:
                  summary: Update initiated
                  value:
                    status: "updating"
                    message: "Firmware update in progress"
        
        '400':
          description: Invalid firmware file or update failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/node/restart:
    post:
      summary: Restart the system
      description: |
        Triggers a system restart. The response will be sent
        before the restart occurs.
      
      tags:
        - System Management
      
      responses:
        '200':
          description: System restart initiated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RestartResponse'
              examples:
                default:
                  summary: Restart initiated
                  value:
                    status: "restarting"

components:
  schemas:
    TaskStatusResponse:
      type: object
      required:
        - summary
        - tasks
        - system
      properties:
        summary:
          $ref: '#/components/schemas/TaskSummary'
        tasks:
          type: array
          items:
            $ref: '#/components/schemas/TaskInfo'
        system:
          $ref: '#/components/schemas/SystemInfo'
    
    TaskSummary:
      type: object
      required:
        - totalTasks
        - activeTasks
      properties:
        totalTasks:
          type: integer
          minimum: 0
          description: Total number of registered tasks
          example: 6
        activeTasks:
          type: integer
          minimum: 0
          description: Number of currently enabled tasks
          example: 5
    
    TaskInfo:
      type: object
      required:
        - name
        - interval
        - enabled
        - running
        - autoStart
      properties:
        name:
          type: string
          description: Unique task identifier
          example: "discovery_send"
        interval:
          type: integer
          minimum: 1
          description: Execution frequency in milliseconds
          example: 1000
        enabled:
          type: boolean
          description: Whether task is currently enabled
          example: true
        running:
          type: boolean
          description: Whether task is actively executing
          example: true
        autoStart:
          type: boolean
          description: Whether task starts automatically
          example: true
    
    SystemInfo:
      type: object
      required:
        - freeHeap
        - uptime
      properties:
        freeHeap:
          type: integer
          minimum: 0
          description: Available RAM in bytes
          example: 48748
        uptime:
          type: integer
          minimum: 0
          description: System uptime in milliseconds
          example: 12345
    
    TaskControlResponse:
      type: object
      required:
        - success
        - message
        - task
        - action
      properties:
        success:
          type: boolean
          description: Whether the operation was successful
          example: true
        message:
          type: string
          description: Human-readable operation result
          example: "Task enabled"
        task:
          type: string
          description: Name of the task that was operated on
          example: "heartbeat"
        action:
          type: string
          description: Action that was performed
          example: "enable"
    
    TaskStatusDetailResponse:
      allOf:
        - $ref: '#/components/schemas/TaskControlResponse'
        - type: object
          required:
            - taskDetails
          properties:
            taskDetails:
              $ref: '#/components/schemas/TaskDetailInfo'
    
    TaskDetailInfo:
      type: object
      required:
        - name
        - enabled
        - running
        - interval
        - system
      properties:
        name:
          type: string
          description: Task name
          example: "discovery_send"
        enabled:
          type: boolean
          description: Whether task is enabled
          example: true
        running:
          type: boolean
          description: Whether task is running
          example: true
        interval:
          type: integer
          description: Task execution interval
          example: 1000
        system:
          $ref: '#/components/schemas/SystemInfo'
    
    SystemStatusResponse:
      type: object
      required:
        - freeHeap
        - chipId
        - sdkVersion
        - cpuFreqMHz
        - flashChipSize
        - api
      properties:
        freeHeap:
          type: integer
          description: Available RAM in bytes
          example: 48748
        chipId:
          type: integer
          description: ESP8266 chip ID
          example: 12345678
        sdkVersion:
          type: string
          description: ESP8266 SDK version
          example: "3.1.2"
        cpuFreqMHz:
          type: integer
          description: CPU frequency in MHz
          example: 80
        flashChipSize:
          type: integer
          description: Flash chip size in bytes
          example: 1048576
        api:
          type: array
          items:
            $ref: '#/components/schemas/ApiEndpoint'
    
    ApiEndpoint:
      type: object
      required:
        - uri
        - method
      properties:
        uri:
          type: string
          description: API endpoint URI
          example: "/api/node/status"
        method:
          type: integer
          description: HTTP method (1=GET, 3=POST)
          example: 1
    
    ClusterMembersResponse:
      type: object
      required:
        - members
      properties:
        members:
          type: array
          items:
            $ref: '#/components/schemas/ClusterNode'
    
    ClusterNode:
      type: object
      required:
        - hostname
        - ip
        - lastSeen
        - latency
        - status
        - resources
        - api
      properties:
        hostname:
          type: string
          description: Node hostname
          example: "spore-node-1"
        ip:
          type: string
          format: ipv4
          description: Node IP address
          example: "192.168.1.100"
        lastSeen:
          type: integer
          description: Timestamp of last communication
          example: 1234567890
        latency:
          type: integer
          description: Network latency in milliseconds
          example: 5
        status:
          type: string
          enum: [ACTIVE, INACTIVE, DEAD]
          description: Node health status
          example: "ACTIVE"
        resources:
          $ref: '#/components/schemas/SystemResources'
        api:
          type: array
          items:
            $ref: '#/components/schemas/ApiEndpoint'
    
    SystemResources:
      type: object
      required:
        - freeHeap
        - chipId
        - sdkVersion
        - cpuFreqMHz
        - flashChipSize
      properties:
        freeHeap:
          type: integer
          description: Available RAM in bytes
          example: 48748
        chipId:
          type: integer
          description: ESP8266 chip ID
          example: 12345678
        sdkVersion:
          type: string
          description: ESP8266 SDK version
          example: "3.1.2"
        cpuFreqMHz:
          type: integer
          description: CPU frequency in MHz
          example: 80
        flashChipSize:
          type: integer
          description: Flash chip size in bytes
          example: 1048576
    
    UpdateResponse:
      type: object
      required:
        - status
      properties:
        status:
          type: string
          enum: [updating, failed]
          description: Update operation status
          example: "updating"
        message:
          type: string
          description: Additional status information
          example: "Firmware update in progress"
    
    RestartResponse:
      type: object
      required:
        - status
      properties:
        status:
          type: string
          enum: [restarting]
          description: Restart operation status
          example: "restarting"
    
    ErrorResponse:
      type: object
      required:
        - success
        - message
      properties:
        success:
          type: boolean
          description: Always false for error responses
          example: false
        message:
          type: string
          description: Error description
          example: "Missing parameters. Required: task, action"
        example:
          type: string
          description: Example of correct usage
          example: "{\"task\": \"discovery_send\", \"action\": \"status\"}"
        task:
          type: string
          description: Task name (if applicable)
          example: "heartbeat"
        action:
          type: string
          description: Action attempted (if applicable)
          example: "invalid_action"

tags:
  - name: Task Management
    description: Operations for monitoring and controlling background tasks
  - name: System Status
    description: System resource monitoring and API information
  - name: Cluster Management
    description: Multi-node cluster coordination and health monitoring
  - name: System Management
    description: System-level operations like updates and restarts

externalDocs:
  description: SPORE Project Documentation
  url: https://github.com/your-org/spore