Skip to content

API.md

Latest commit

 

History

History
288 lines (222 loc) · 4.29 KB

API.md

File metadata and controls

288 lines (222 loc) · 4.29 KB

API Reference

The backend provides a REST API for device control and data access. All endpoints require authentication except /health.

Base URL

http://localhost:8000

Authentication

All API endpoints (except /health and /api/login) require a Bearer token.

Login

POST /api/login
Content-Type: application/json

{
  "password": "your_password"
}

Response:

{
  "access_token": "eyJ0eXAiOiJKV1QiLCJh...",
  "token_type": "bearer"
}

Use the token in subsequent requests:

Authorization: Bearer eyJ0eXAiOiJKV1QiLCJh...

Device Control

Get Device Status

GET /api/status

Response:

{
  "power": true,
  "current_humidity": 65,
  "target_humidity": 60,
  "temperature": 23.5,
  "fan_speed": "high",
  "mode": "normal",
  "tank_full": false,
  "timer": 0,
  "timestamp": "2024-12-03T10:30:00"
}

Set Power

POST /api/power
Content-Type: application/json

{
  "value": true
}

Set Target Humidity

POST /api/humidity
Content-Type: application/json

{
  "value": 55
}

Value must be between 30 and 80.

Set Fan Speed

POST /api/fan
Content-Type: application/json

{
  "value": "high"
}

Valid values: low, high

Set Timer

POST /api/timer
Content-Type: application/json

{
  "value": 4
}

Value is hours (0-24). 0 means timer off.

Data Retrieval

Get Historical Data

GET /api/history?hours=24

Query parameters:

  • hours - Number of hours to retrieve (default: 24)
  • from_date - ISO 8601 start date (optional)
  • to_date - ISO 8601 end date (optional)

Response:

{
  "count": 1440,
  "readings": [
    {
      "timestamp": "2024-12-03T10:30:00",
      "current_humidity": 65,
      "target_humidity": 60,
      "temperature": 23.5,
      "power": true,
      "fan_speed": "high"
    }
  ]
}

Get Events

GET /api/events?limit=100&offset=0&event_type=all

Query parameters:

  • limit - Number of events to return (default: 100)
  • offset - Pagination offset (default: 0)
  • event_type - Filter by type: all, user, system, power, humidity, temperature (default: all)

Response:

{
  "count": 100,
  "total": 450,
  "events": [
    {
      "id": 123,
      "timestamp": "2024-12-03T10:30:00",
      "event_type": "humidity_changed",
      "description": "Target humidity changed from 60% to 55%",
      "user_initiated": true,
      "old_value": "60",
      "new_value": "55"
    }
  ]
}

Get Statistics

GET /api/statistics?period=today

Query parameters:

  • period - Time period: today, week, month, all (default: today)

Response:

{
  "period": "today",
  "avg_humidity": 62.5,
  "avg_temperature": 23.2,
  "min_humidity": 58,
  "max_humidity": 70,
  "min_temperature": 22.1,
  "max_temperature": 24.3,
  "total_readings": 720,
  "runtime_hours": 8.5,
  "tank_full_count": 0
}

Configuration

Get Configuration

GET /api/config

Response:

{
  "polling_interval": 60
}

Set Polling Interval

POST /api/config/interval
Content-Type: application/json

{
  "value": 30
}

Value is in seconds. Minimum 10, recommended 60.

WebSocket

For real-time updates, connect to the WebSocket endpoint:

ws://localhost:8000/ws

The server will push device status updates automatically whenever the device state changes.

Message format:

{
  "power": true,
  "current_humidity": 65,
  "target_humidity": 60,
  "temperature": 23.5,
  "fan_speed": "high",
  "mode": "normal",
  "tank_full": false,
  "timer": 0,
  "timestamp": "2024-12-03T10:30:00"
}

Health Check

GET /health

No authentication required. Returns:

{
  "status": "ok",
  "timestamp": "2024-12-03T10:30:00",
  "polling_active": true
}

Error Responses

All endpoints return standard HTTP status codes:

  • 200 - Success
  • 400 - Bad Request (invalid parameters)
  • 401 - Unauthorized (missing or invalid token)
  • 500 - Internal Server Error

Error response format:

{
  "detail": "Error message here"
}

Interactive Documentation

The backend provides auto-generated interactive API documentation at:

These interfaces allow you to test API endpoints directly from your browser.