feat: basic cluster overview
This commit is contained in:
669
api/openapi.yaml
Normal file
669
api/openapi.yaml
Normal file
@@ -0,0 +1,669 @@
|
||||
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
|
||||
Reference in New Issue
Block a user