spore/api/README.md

# 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.