ADR-130: HOMECORE-API — Wire-compatible REST and WebSocket API

1. Context

Home Assistant's HTTP and WebSocket APIs are the primary interface for every non-frontend client: the iOS companion app, the Android companion app, HACS, Node-RED, the homeassistant Python client library, ESPHome native API clients, external automation scripts, and the hundreds of third-party HA dashboard projects.

The API surface is defined in two Python modules:

1. homeassistant/components/api/__init__.py — 24 REST API routes mounted at /api/. Key routes: GET /api/, GET /api/states, GET /api/states/<entity_id>, POST /api/states/<entity_id>, GET /api/events, POST /api/events/<event_type>, GET /api/services, POST /api/services/<domain>/<service>, GET /api/error_log, GET /api/config, POST /api/template, POST /api/check_config, GET /api/history/period/<datetime> (deprecated — recorder), POST /api/logbook/ (deprecated — recorder).

2. homeassistant/components/websocket_api/ — the WebSocket API handler (connection.py handles auth handshake; commands.py handles 30+ command types). Key commands: auth, subscribe_events, unsubscribe_events, call_service, get_states, get_services, get_config, subscribe_trigger, render_template, validate_config, subscribe_entities (entity registry updates), config/entity_registry/list, and many more.

1.1 Auth model

HA uses long-lived access tokens (LLAT) as the primary auth mechanism for non-UI clients. Tokens are created in the HA user profile UI and stored in .storage/auth. The REST API accepts Authorization: Bearer <token> or the api_password legacy header (deprecated since HA 2022.x). The WebSocket API requires an auth message with access_token as the first message after connection.

1.2 Why wire-compat matters

The iOS and Android HA companion apps (>100,000 installs combined) hardcode the HA API paths and WebSocket command schemas. Any implementation that deviates from the exact JSON schemas causes the apps to fail silently — not with a meaningful error, but by returning empty entity lists or missing state updates. Wire-compat is therefore a hard requirement, not a nice-to-have.

The baseline for compatibility is HA 2025.1 (the version that introduced SQLite recorder schema version 48). Any HOMECORE instance claiming compliance with this ADR must pass the companion app integration test suite.

2. Decision

Implement the homecore-api crate as an Axum-based server that replicates the HA REST and WebSocket API on port 8123. The implementation is informed by — but does not copy — homeassistant/components/api/__init__.py and homeassistant/components/websocket_api/.

The server reuses the Axum + Tokio architecture established in v2/crates/wifi-densepose-sensing-server/src/main.rs and its bearer auth pattern (v2/crates/wifi-densepose-sensing-server/src/bearer_auth.rs).

2.1 REST API route table

2.2 WebSocket API command table

2.3 Auth implementation

HOMECORE-API implements long-lived access tokens as JWTs signed with an Ed25519 key (generated at first startup, stored in .homecore/auth_key.pem). Token format:

{
  "sub": "<user_id>",
  "iss": "homecore",
  "iat": <unix_timestamp>,
  "exp": <unix_timestamp or null for LLAT>,
  "type": "long_lived_access_token"
}

The HA companion app sends Authorization: Bearer <token> on every REST request. The WebSocket auth handshake sends { "type": "auth", "access_token": "<token>" }. Both paths validate the JWT against the stored Ed25519 key.

Legacy api_password is deliberately not supported (removed in HA 2022.x and never properly secure).

3. HA-side reference table

4. Public API parity table

5. Phased implementation plan

P1 — Axum skeleton + static frontend (1 week)

• Create v2/crates/homecore-api/ workspace member.
• Axum router on port 8123; Tower CORS middleware (allow http://homeassistant.local:8123).
• Static file handler: serve HA's Python frontend build from a configurable path (default ./frontend/build/). This allows using the Python HA frontend as-is until ADR-131 ships.
• GET /api/ returns { "message": "API running." }.
• CI: cargo check -p homecore-api; HTTP smoke test.

P2 — Core REST + WebSocket auth + states (3 weeks)

• Axum WebSocket upgrade at /api/websocket.
• Auth: Ed25519 JWT issuance at /auth/token; validation middleware.
• WS auth handshake: auth_required → auth → auth_ok / auth_invalid.
• WS commands: get_states, subscribe_events, unsubscribe_events, call_service, get_services, get_config.
• REST: /api/states, /api/states/<entity_id> (GET + POST), /api/services, /api/services/<domain>/<service>, /api/config.
• Integration test: HA iOS companion app authenticates and displays entity list against HOMECORE.

P3 — Remaining WS commands + entity registry API (3 weeks)

• WS: subscribe_trigger, render_template, validate_config, subscribe_entities, entity/area/device registry commands.
• REST: /api/template, /api/webhook/<id>, /api/error_log, /api/events, /api/events/<type>.
• /auth/authorize OAuth2 flow for UI login.
• HACS smoke test: HACS connects, lists integrations.

P4 — Recorder + history API (2 weeks)

• /api/history/period/<datetime> backed by ADR-132 recorder SQLite.
• /api/logbook/ backed by ADR-132 recorder.
• /api/camera_proxy/, /api/calendar/, /api/intent/handle.
• Companion app full feature test: automations, notifications, history charts.

6. Risks

7. Open questions

Q1: The HA WebSocket API uses incremental integer IDs (id: 1, 2, 3, ...) for command/response correlation within a session. HOMECORE uses the same scheme. What is the maximum id value the companion app supports before wrapping? If the app doesn't wrap and HOMECORE processes > 2^31 commands per session, this becomes an overflow issue in extremely long-lived sessions.

Q2: The subscribe_entities WS command (added in HA 2021.x) sends entity registry change events in addition to state change events. The iOS companion app uses this to maintain a local entity list without polling. Is the full subscribe_entities delta schema (including action: "create" | "update" | "remove") fully documented, or must it be reverse-engineered from the companion app source?

Q3: HA's /auth/token endpoint accepts grant_type=password (username/password) and grant_type=refresh_token. HOMECORE's initial implementation supports password grant only. Is refresh token support required for the companion app (it caches tokens between sessions) or does the companion app re-authenticate on each launch?

Q4: CORS policy: HA's default CORS allows http://localhost:* and http://homeassistant.local:*. The HOMECORE-UI frontend (ADR-131) will be served from a different origin in development. What CORS policy should HOMECORE-API use in production vs development mode?

8. References

HA upstream

• homeassistant/components/api/__init__.py — 24 REST routes with exact URL paths, methods, and JSON response schemas
• homeassistant/components/websocket_api/connection.py — auth handshake protocol; per-connection state management
• homeassistant/components/websocket_api/commands.py — 30+ command type handlers with exact type strings and result schemas
• homeassistant/components/http/__init__.py — CORS setup; trusted proxy handling; aiohttp-based server
• homeassistant/auth/providers/__init__.py — token issuance; AuthManager; LLAT format
• homeassistant/auth/__init__.py — AuthManager.async_create_long_lived_access_token

This repo

• v2/crates/wifi-densepose-sensing-server/src/main.rs — Axum server architecture (REST + WebSocket); pattern for this ADR
• v2/crates/wifi-densepose-sensing-server/src/bearer_auth.rs — Bearer auth middleware pattern
• docs/adr/ADR-127-homecore-state-machine-rust.md — state machine that REST/WS routes read from
• docs/adr/ADR-126-ruview-native-ha-port-master.md — §6 compatibility contract with companion apps

External

• HA WebSocket API Developer Docs — authoritative command type catalog
• HA REST API — REST endpoint schemas