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:**
```json
{
  "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:**
```json
{
  "success": true,
  "message": "Task enabled",
  "task": "heartbeat",
  "action": "enable"
}
```

**Task Status Response:**
```json
{
  "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/`](../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`](../api/README.md) for detailed usage instructions.

## Usage Examples

### Basic Task Status Check
```bash
curl -s http://10.0.1.60/api/tasks/status | jq '.'
```

### Task Control
```bash
# 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
```bash
# 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
```python
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
```javascript
// 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
```bash
# 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
```bash
# 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
```bash
# 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
```