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
2. Copy and paste the contents of openapi.yaml
3. View the interactive documentation

Option B: Local Swagger UI

# 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

# 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

# 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

# Install OpenAPI validator
npm install -g @apidevtools/swagger-parser

# Validate the specification
swagger-parser validate openapi.yaml

4. Generate Mock Server

Using Prism (Stoplight)

# 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

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

Task Control

# 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

# 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

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

// 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
• OpenAPI Generator
• Swagger Codegen
• Swagger UI
• Prism Mock Server
• OpenAPI Validator

License

This API specification is part of the SPORE project and follows the same license terms.