feat: task manager endpoint, updated documentation

api/README.md

@@ -0,0 +1,201 @@
+# SPORE API Documentation
+
+This folder contains the OpenAPI specification for the SPORE embedded system API.
+
+## Files
+
+- **`openapi.yaml`** - OpenAPI 3.0 specification file
+- **`README.md`** - This documentation file
+
+## OpenAPI Specification
+
+The `openapi.yaml` file provides a complete, machine-readable specification of the SPORE API. It can be used with various tools 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
+
+## Using the OpenAPI Specification
+
+### 1. View Interactive Documentation
+
+#### Option A: Swagger UI Online
+1. Go to [Swagger Editor](https://editor.swagger.io/)
+2. Copy and paste the contents of `openapi.yaml`
+3. View the interactive documentation
+
+#### Option B: Local Swagger UI
+```bash
+# Install Swagger UI locally
+npm install -g swagger-ui-express
+
+# Or use Docker
+docker run -p 8080:8080 -e SWAGGER_JSON=/openapi.yaml -v $(pwd):/swagger swaggerapi/swagger-ui
+```
+
+### 2. Generate Client Libraries
+
+#### Using OpenAPI Generator
+```bash
+# Install OpenAPI Generator
+npm install @openapitools/openapi-generator-cli -g
+
+# Generate Python client
+openapi-generator generate -i openapi.yaml -g python -o python-client
+
+# Generate JavaScript client
+openapi-generator generate -i openapi.yaml -g javascript -o js-client
+
+# Generate C# client
+openapi-generator generate -i openapi.yaml -g csharp -o csharp-client
+```
+
+#### Using Swagger Codegen
+```bash
+# Install Swagger Codegen
+npm install -g swagger-codegen
+
+# Generate Python client
+swagger-codegen generate -i openapi.yaml -l python -o python-client
+
+# Generate Java client
+swagger-codegen generate -i openapi.yaml -l java -o java-client
+```
+
+### 3. Validate API Responses
+
+#### Using OpenAPI Validator
+```bash
+# Install OpenAPI validator
+npm install -g @apidevtools/swagger-parser
+
+# Validate the specification
+swagger-parser validate openapi.yaml
+```
+
+### 4. Generate Mock Server
+
+#### Using Prism (Stoplight)
+```bash
+# Install Prism
+npm install -g @stoplight/prism-cli
+
+# Start mock server
+prism mock openapi.yaml
+
+# The mock server will be available at http://localhost:4010
+```
+
+## API Endpoints Overview
+
+The SPORE API provides the following main categories of endpoints:
+
+### Task Management
+- **`GET /api/tasks/status`** - Get comprehensive task status
+- **`POST /api/tasks/control`** - Control individual tasks
+
+### System Status
+- **`GET /api/node/status`** - Get system resource information
+- **`GET /api/cluster/members`** - Get cluster membership
+
+### System Management
+- **`POST /api/node/update`** - Handle OTA firmware updates
+- **`POST /api/node/restart`** - Trigger system restart
+
+## Data Models
+
+The OpenAPI specification includes comprehensive schemas for:
+
+- **Task Information**: Task status, configuration, and execution details
+- **System Resources**: Memory usage, chip information, and performance metrics
+- **Cluster Management**: Node health, network topology, and resource sharing
+- **API Responses**: Standardized response formats and error handling
+
+## Examples
+
+### Basic Task Status Check
+```bash
+curl -s http://192.168.1.100/api/tasks/status | jq '.'
+```
+
+### Task Control
+```bash
+# Disable a task
+curl -X POST http://192.168.1.100/api/tasks/control \
+  -d "task=heartbeat&action=disable"
+
+# Get detailed status
+curl -X POST http://192.168.1.100/api/tasks/control \
+  -d "task=discovery_send&action=status"
+```
+
+### System Monitoring
+```bash
+# Check system resources
+curl -s http://192.168.1.100/api/node/status | jq '.freeHeap'
+
+# Monitor cluster health
+curl -s http://192.168.1.100/api/cluster/members | jq '.members[].status'
+```
+
+## Integration Examples
+
+### Python Client
+```python
+import requests
+
+# Get task status
+response = requests.get('http://192.168.1.100/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://192.168.1.100/api/tasks/control', data=control_data)
+```
+
+### JavaScript Client
+```javascript
+// Get task status
+fetch('http://192.168.1.100/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://192.168.1.100/api/tasks/control', {
+  method: 'POST',
+  headers: {'Content-Type': 'application/x-www-form-urlencoded'},
+  body: 'task=heartbeat&action=disable'
+});
+```
+
+## Contributing
+
+When adding new API endpoints or modifying existing ones:
+
+1. Update the `openapi.yaml` file
+2. Add appropriate schemas for new data models
+3. Include example responses
+4. Update this README if needed
+5. Test the specification with validation tools
+
+## Tools and Resources
+
+- [OpenAPI Specification](https://swagger.io/specification/)
+- [OpenAPI Generator](https://openapi-generator.tech/)
+- [Swagger Codegen](https://github.com/swagger-api/swagger-codegen)
+- [Swagger UI](https://swagger.io/tools/swagger-ui/)
+- [Prism Mock Server](https://stoplight.io/open-source/prism/)
+- [OpenAPI Validator](https://apitools.dev/swagger-parser/)
+
+## License
+
+This API specification is part of the SPORE project and follows the same license terms.