44r0n7
59fb56558f
Add the static HTTP dashboard example and wire in the recent daemon/API polish: CORS-aware API routing, service-install behavior cleanup, safer systemd unit ExecStart quoting, and friendly-name validation for path-safe targeting. Also refresh README/API/roadmap docs, remove the temporary claude observations file, and include the related tests for API/status and daemon validation.
72 lines
1.8 KiB
Markdown
72 lines
1.8 KiB
Markdown
# API.md
|
|
# tvctl HTTP API Specification
|
|
|
|
`tvctl` exposes a loopback-only HTTP API for tool builders at `/v1/...`.
|
|
This file captures the v1 surface promised by the design bundle so the
|
|
repository has a dedicated API spec from day one.
|
|
|
|
For browser-based tools, CORS is opt-in via daemon config.
|
|
|
|
## Base URL
|
|
|
|
`http://127.0.0.1:7272/v1`
|
|
|
|
## Response Envelope
|
|
|
|
Successful responses:
|
|
|
|
```json
|
|
{ "ok": true, "data": { "...": "..." } }
|
|
```
|
|
|
|
Error responses:
|
|
|
|
```json
|
|
{
|
|
"ok": false,
|
|
"error": {
|
|
"code": "device_not_found",
|
|
"message": "No device with id 'living-room' exists.",
|
|
"hint": "Run tvctl device list to see known devices."
|
|
}
|
|
}
|
|
```
|
|
|
|
## Planned Routes
|
|
|
|
- `GET /devices`
|
|
- `POST /devices/discover`
|
|
- `GET /devices/{id}`
|
|
- `DELETE /devices/{id}`
|
|
- `GET /devices/{id}/state`
|
|
- `GET /devices/{id}/apps`
|
|
- `POST /devices/{id}/apps/launch`
|
|
- `POST /devices/{id}/apps/stop`
|
|
- `POST /devices/{id}/apps/refresh`
|
|
- `POST /devices/{id}/remote/key`
|
|
- `POST /devices/{id}/remote/sequence`
|
|
- `POST /devices/{id}/dev/install`
|
|
- `POST /devices/{id}/dev/reload`
|
|
- `GET /devices/{id}/dev/logs`
|
|
- `GET /daemon/status`
|
|
- `GET /config`
|
|
- `PATCH /config`
|
|
- `POST /config/reload`
|
|
|
|
## API Rules
|
|
|
|
- All routes return the standard JSON envelope.
|
|
- `error.code` values are stable machine contracts.
|
|
- `error.hint` is optional but recommended for user-actionable failures.
|
|
- Devices may be addressed by UUID or friendly name.
|
|
- Path targets must be URL-encoded by clients (for example `Living Room TV` -> `Living%20Room%20TV`).
|
|
- User-supplied friendly names are trimmed; `/` and `%` are rejected (`invalid_device_name`).
|
|
- Platform-specific field names must not leak past the adapter layer.
|
|
- Browser clients require `daemon.cors_enabled = true` and explicit `daemon.cors_allowed_origins`.
|
|
|
|
## Dashboard Example
|
|
|
|
An endpoint coverage dashboard is included at:
|
|
|
|
`examples/http-dashboard/`
|