130 lines
2.7 KiB
Markdown
130 lines
2.7 KiB
Markdown
# 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)
|
|
|
|
```bash
|
|
poetry run uvicorn apps.api.main:app --reload
|
|
```
|
|
|
|
### Production Mode
|
|
|
|
```bash
|
|
poetry run uvicorn apps.api.main:app --host 0.0.0.0 --port 8001
|
|
```
|
|
|
|
### Using Python directly
|
|
|
|
```bash
|
|
poetry run python -m apps.api.main
|
|
```
|
|
|
|
### Docker Container
|
|
|
|
#### Build Image
|
|
|
|
```bash
|
|
docker build -t api:dev -f apps/api/Dockerfile .
|
|
```
|
|
|
|
#### Run Container
|
|
|
|
```bash
|
|
docker run --rm -p 8001:8001 \
|
|
-v $(pwd)/config:/app/config:ro \
|
|
-e MQTT_BROKER=172.16.2.16 \
|
|
-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):**
|
|
```bash
|
|
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:**
|
|
```json
|
|
{
|
|
"status": "ok"
|
|
}
|
|
```
|
|
|
|
### `GET /spec`
|
|
|
|
Returns supported capabilities and their versions.
|
|
|
|
**Response:**
|
|
```json
|
|
{
|
|
"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
|