home-automation/apps/api/README.md

Home Automation API

FastAPI-based REST API for the home automation system.

Features

• Health Check: Monitor API availability
• Capabilities Specification: Discover supported capabilities and versions
• CORS Support: Configured for local frontend development
• Auto-generated Documentation: Interactive API docs via Swagger UI

Running the API

Development Mode (with auto-reload)

poetry run uvicorn apps.api.main:app --reload

Production Mode

poetry run uvicorn apps.api.main:app --host 0.0.0.0 --port 8001

Using Python directly

poetry run python -m apps.api.main

Docker Container

Build Image

docker build -t api:dev -f apps/api/Dockerfile .

Run Container

docker run --rm -p 8001:8001 \
  -v $(pwd)/config:/app/config:ro \
  -e MQTT_BROKER=172.23.1.102 \
  -e MQTT_PORT=1883 \
  -e REDIS_HOST=172.23.1.116 \
  -e REDIS_PORT=6379 \
  -e REDIS_DB=8 \
  -e REDIS_CHANNEL=ui:updates \
  api:dev

Mit Docker Network (empfohlen für Linux):

docker network create home-automation
docker run --rm -p 8001:8001 \
  --network home-automation \
  --name api \
  -v $(pwd)/config:/app/config:ro \
  -e MQTT_BROKER=172.16.2.16 \
  -e REDIS_HOST=172.23.1.116 \
  -e REDIS_DB=8 \
  api:dev

Hinweise:

• Linux: Port wird auf 0.0.0.0:8001 gebunden (von überall erreichbar)
• macOS/finch: Port wird auf 127.0.0.1:8001 gebunden (nur localhost)

Environment Variables

Variable	Default	Description
MQTT_BROKER	172.16.2.16	MQTT broker hostname/IP
MQTT_PORT	1883	MQTT broker port
REDIS_HOST	localhost	Redis server hostname/IP
REDIS_PORT	6379	Redis server port
REDIS_DB	0	Redis database number
REDIS_CHANNEL	ui:updates	Redis pub/sub channel

API Endpoints

GET /health

Health check endpoint.

Response:

{
  "status": "ok"
}

GET /spec

Returns supported capabilities and their versions.

Response:

{
  "capabilities": {
    "light": "light@1.2.0"
  }
}

Interactive Documentation

Once the server is running, visit:

• Swagger UI: http://localhost:8000/docs
• ReDoc: http://localhost:8000/redoc
• OpenAPI Schema: http://localhost:8000/openapi.json

CORS Configuration

The API is configured to accept requests from the following origins:

• http://localhost:3000
• http://localhost:5173
• http://localhost:8080
• http://127.0.0.1:3000
• http://127.0.0.1:5173
• http://127.0.0.1:8080

Dependencies

• FastAPI: Modern, fast web framework
• Uvicorn: ASGI server
• Pydantic: Data validation using Python type hints