Initial commit

doc/api.md

@@ -0,0 +1,133 @@
+# API Reference
+
+## Base Behavior
+
+- Base URL: same origin as UI host.
+- UI route:
+  - `GET /` returns the dashboard HTML shell.
+- API route namespace:
+  - All API endpoints are under `/api/...`.
+- Cache behavior:
+  - Responses under `/api/` and `/static/` include no-store cache headers.
+
+## Authentication Model
+
+- Login endpoint sets a session value on success.
+- Protected endpoints require `Depends(require_auth)`.
+- Session cookie behavior:
+  - `same_site=lax`
+  - max age: 8 hours
+  - secure flag controlled by `SESSION_COOKIE_SECURE`
+
+Related references:
+
+- Configuration: `doc/environment.md`
+- Auth implementation: `app/auth.py`
+
+## Error Contract
+
+- `401` for authentication failures.
+- `400` for missing required node configuration values.
+- `422` for request validation and unsupported chart window values.
+- `502` for RPC or SSH operation failures.
+- Error shape for handled exceptions:
+  - `{ "detail": "<message>" }`
+
+## Endpoint Contracts
+
+### Health and Session
+
+| Method | Path | Auth | Description |
+| --- | --- | --- | --- |
+| `GET` | `/api/health` | No | Returns service liveness: `{ "ok": true }`. |
+| `GET` | `/api/auth/me` | No | Returns current authentication state and username if authenticated. |
+| `POST` | `/api/auth/login` | No | Validates credentials and creates session. |
+| `POST` | `/api/auth/logout` | Yes | Clears session. |
+
+`POST /api/auth/login` request body:
+
+```json
+{
+  "username": "admin",
+  "password": "secret"
+}
+```
+
+### Node Settings
+
+| Method | Path | Auth | Description |
+| --- | --- | --- | --- |
+| `GET` | `/api/settings` | Yes | Returns persisted node connection and control settings. |
+| `PUT` | `/api/settings` | Yes | Validates and persists node settings. |
+
+`PUT /api/settings` request body fields:
+
+- `rpc_url` string
+- `rpc_username` string
+- `rpc_password` string
+- `rpc_wallet` string
+- `config_path` string
+- `ssh_host` string
+- `ssh_port` integer `1..65535`
+- `ssh_username` string
+- `ssh_password` string
+- `ssh_key_path` string
+- `bitcoin_binary` string
+
+All string fields are trimmed before persistence.
+
+### Dashboard
+
+| Method | Path | Auth | Description |
+| --- | --- | --- | --- |
+| `GET` | `/api/dashboard/summary` | Yes | Returns chain, network, mempool, mining, uptime, optional wallet data, and `updated_at`. |
+| `GET` | `/api/dashboard/history` | Yes | Returns metric history for query-param `window` and `limit`. |
+| `GET` | `/api/dashboard/history/{window}` | Yes | Same as above with `window` as a path parameter. |
+
+Supported `window` values:
+
+- `5m`
+- `30m`
+- `2h`
+- `6h`
+- `all`
+
+`limit` is clamped server-side to `[1, 20000]`.
+
+### RPC Explorer
+
+| Method | Path | Auth | Description |
+| --- | --- | --- | --- |
+| `POST` | `/api/rpc/call` | Yes | Executes a JSON-RPC method with params and optional wallet override. |
+| `GET` | `/api/rpc/commands` | Yes | Calls node `help` and returns parsed method catalog. |
+| `GET` | `/api/rpc/help/{method_name}` | Yes | Returns detailed `help` output for one method. |
+
+`POST /api/rpc/call` request body:
+
+```json
+{
+  "method": "getblockchaininfo",
+  "params": [],
+  "wallet": null
+}
+```
+
+### Node Actions
+
+| Method | Path | Auth | Description |
+| --- | --- | --- | --- |
+| `POST` | `/api/actions/stop` | Yes | Calls RPC `stop`. |
+| `POST` | `/api/actions/start` | Yes | Runs SSH start command built from persisted settings. |
+| `POST` | `/api/actions/restart` | Yes | Attempts RPC stop then runs SSH start command. |
+
+Action responses include action metadata and remote execution payload when SSH is involved.
+
+## Operational Notes
+
+- Startup and restart require:
+  - valid SSH connectivity
+  - `config_path`
+  - SSH user credentials or key access
+- When running in Docker, `rpc_url` should usually target `host.docker.internal` if the node is on the Docker host.
+
+See `doc/build-and-deploy.md` for Docker network details.