spore/docs/API.md

SPORE API Documentation

The SPORE system provides a comprehensive RESTful API for monitoring and controlling the embedded device. All endpoints return JSON responses and support standard HTTP status codes.

Quick Reference

Task Management API

Endpoint	Method	Description	Parameters	Response
/api/tasks/status	GET	Get comprehensive status of all tasks and system information	None	Task status overview with system metrics
/api/tasks/control	POST	Control individual task operations	task, action	Operation result with task details

System Status API

Endpoint	Method	Description	Response
/api/node/status	GET	System resource information and API endpoint registry	System metrics and API catalog
/api/cluster/members	GET	Cluster membership and node health information	Cluster topology and health status
/api/node/update	POST	Handle firmware updates via OTA	Update progress and status
/api/node/restart	POST	Trigger system restart	Restart confirmation

Detailed API Reference

Task Management

GET /api/tasks/status

Returns comprehensive status information for all registered tasks, including system resource metrics and task execution details.

Response Fields:

Field	Type	Description
summary.totalTasks	integer	Total number of registered tasks
summary.activeTasks	integer	Number of currently enabled tasks
tasks[].name	string	Unique task identifier
tasks[].interval	integer	Execution frequency in milliseconds
tasks[].enabled	boolean	Whether task is currently enabled
tasks[].running	boolean	Whether task is actively executing
tasks[].autoStart	boolean	Whether task starts automatically
system.freeHeap	integer	Available RAM in bytes
system.uptime	integer	System uptime in milliseconds

Example Response:

{
  "summary": {
    "totalTasks": 6,
    "activeTasks": 5
  },
  "tasks": [
    {
      "name": "discovery_send",
      "interval": 1000,
      "enabled": true,
      "running": true,
      "autoStart": true
    }
  ],
  "system": {
    "freeHeap": 48748,
    "uptime": 12345
  }
}

POST /api/tasks/control

Controls the execution state of individual tasks. Supports enabling, disabling, starting, stopping, and getting detailed status for specific tasks.

Parameters:

• task (required): Name of the task to control
• action (required): Action to perform

Available Actions:

Action	Description	Use Case
enable	Enable a disabled task	Resume background operations
disable	Disable a running task	Pause resource-intensive tasks
start	Start a stopped task	Begin task execution
stop	Stop a running task	Halt task execution
status	Get detailed status for a specific task	Monitor individual task health

Example Response:

{
  "success": true,
  "message": "Task enabled",
  "task": "heartbeat",
  "action": "enable"
}

Task Status Response:

{
  "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
    }
  }
}

System Status

GET /api/node/status

Returns comprehensive system resource information including memory usage, chip details, and a registry of all available API endpoints.

Response Fields:

• freeHeap: Available RAM in bytes
• chipId: ESP8266 chip ID
• sdkVersion: ESP8266 SDK version
• cpuFreqMHz: CPU frequency in MHz
• flashChipSize: Flash chip size in bytes
• api: Array of registered API endpoints

GET /api/cluster/members

Returns information about all nodes in the cluster, including their health status, resources, and API endpoints.

Response Fields:

• members[]: Array of cluster node information
• hostname: Node hostname
• ip: Node IP address
• lastSeen: Timestamp of last communication
• latency: Network latency in milliseconds
• status: Node health status (ACTIVE, INACTIVE, DEAD)
• resources: System resource information
• api: Available API endpoints

System Management

POST /api/node/update

Initiates an over-the-air firmware update. The firmware file should be uploaded as multipart/form-data.

Parameters:

• firmware: Firmware binary file (.bin)

POST /api/node/restart

Triggers a system restart. The response will be sent before the restart occurs.

HTTP Status Codes

Code	Description	Use Case
200	Success	Operation completed successfully
400	Bad Request	Invalid parameters or action
404	Not Found	Task or endpoint not found
500	Internal Server Error	System error occurred

OpenAPI Specification

A complete OpenAPI 3.0 specification is available in the api/ folder. This specification can be used to:

• Generate client libraries in multiple programming languages
• Create interactive API documentation
• Validate API requests and responses
• Generate mock servers for testing
• Integrate with API management platforms

See api/README.md for detailed usage instructions.

Usage Examples

Basic Task Status Check

curl -s http://10.0.1.60/api/tasks/status | jq '.'

Task Control

# Disable a task
curl -X POST http://10.0.1.60/api/tasks/control \
  -d "task=heartbeat&action=disable"

# Get detailed status
curl -X POST http://10.0.1.60/api/tasks/control \
  -d "task=discovery_send&action=status"

System Monitoring

# Check system resources
curl -s http://10.0.1.60/api/node/status | jq '.freeHeap'

# Monitor cluster health
curl -s http://10.0.1.60/api/cluster/members | jq '.members[].status'

Integration Examples

Python Client

import requests

# Get task status
response = requests.get('http://10.0.1.60/api/tasks/status')
tasks = response.json()

# Check active tasks
active_count = tasks['summary']['activeTasks']
print(f"Active tasks: {active_count}")

# Control a task
control_data = {'task': 'heartbeat', 'action': 'disable'}
response = requests.post('http://10.0.1.60/api/tasks/control', data=control_data)

JavaScript Client

// Get task status
fetch('http://10.0.1.60/api/tasks/status')
  .then(response => response.json())
  .then(data => {
    console.log(`Total tasks: ${data.summary.totalTasks}`);
    console.log(`Active tasks: ${data.summary.activeTasks}`);
  });

// Control a task
fetch('http://10.0.1.60/api/tasks/control', {
  method: 'POST',
  headers: {'Content-Type': 'application/x-www-form-urlencoded'},
  body: 'task=heartbeat&action=disable'
});

Task Management Examples

Monitoring Task Health

# Check overall task status
curl -s http://10.0.1.60/api/tasks/status | jq '.'

# Monitor specific task
curl -s -X POST http://10.0.1.60/api/tasks/control \
  -d "task=heartbeat&action=status" | jq '.'

# Watch for low memory conditions
watch -n 5 'curl -s http://10.0.1.60/api/tasks/status | jq ".system.freeHeap"'

Task Control Workflows

# Temporarily disable discovery to reduce network traffic
curl -X POST http://10.0.1.60/api/tasks/control \
  -d "task=discovery_send&action=disable"

# Check if it's disabled
curl -s -X POST http://10.0.1.60/api/tasks/control \
  -d "task=discovery_send&action=status" | jq '.taskDetails.enabled'

# Re-enable when needed
curl -X POST http://10.0.1.60/api/tasks/control \
  -d "task=discovery_send&action=enable"

Cluster Health Monitoring

# Monitor all nodes in cluster
for ip in 10.0.1.60 10.0.1.61 10.0.1.62; do
  echo "=== Node $ip ==="
  curl -s "http://$ip/api/tasks/status" | jq '.summary'
done