669 lines
19 KiB
YAML
669 lines
19 KiB
YAML
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 |