signalk-apis

Signal K APIs: v1 and v2 have different jobs

The most common misconception about the Signal K server APIs is that v2 is the successor of v1 and v1 is on its way out. Wrong — they serve different purposes and coexist by design:

• v1 is the data-model API. One universal signal tree (navigation.*, environment.*, electrical.*, …) that every source feeds into, exposed three ways: REST snapshot, streaming WebSocket deltas, and PUT actuation. This is the way to read and stream live boat data, and nothing in v2 replaces it.
• v2 is a set of domain APIs — course, resources, notifications, history, autopilot, weather (radar in development) — each a purpose-built REST contract (OpenAPI definitions under Documentation → OpenAPI in the admin UI) for operations the flat data model can't express well ("activate this route", "acknowledge this alarm", "give me yesterday's SOG"). The server owns the routes and keeps the data model consistent. Course and notifications are built into the server; the APIs that front hardware or storage — resources, autopilot, weather, history, radar — are implemented by plugins registering as providers.

New code typically uses both: stream positions over v1 while setting the course over v2.

Consumer side (webapps, external apps)

• Discover, don't hardcode. GET /signalk returns the endpoints — and it advertises v1 only (signalk-http, signalk-ws, signalk-tcp). The v2 APIs are not in the discovery document; they live at the well-known /signalk/v2/api/... paths.
• Read state (v1): GET /signalk/v1/api/vessels/self/<path with dots as slashes> — a leaf returns { value, $source, timestamp, meta } (meta carries units/description; multiple sources for one path appear under values keyed by $source).
• Stream (v1): ws://…/signalk/v1/stream?subscribe=self|all|none, then send { "context": "vessels.self", "subscribe": [{ "path": "navigation.*", "period": 1000 }] }. Gotcha (as of 2.30.0): top-level leaf paths like name and mmsi are not deliverable via subscriptions — poll them over REST instead (signalk-server#2829).
• Operate the boat (v2): e.g. course (GET/PUT /signalk/v2/api/vessels/self/navigation/course/...), resources CRUD (/signalk/v2/api/resources/<type>), notifications (GET/POST /signalk/v2/api/notifications, plus :id/acknowledge, :id/silence, acknowledgeAll, silenceAll, mob — this full surface ships in 2.30.0 even where older docs still mark it as pending). Writes return an envelope like { "state": "COMPLETED", "statusCode": 201, "id": "<uuid>" }.
• Generic actuation (v1 PUT): PUT /signalk/v1/api/vessels/self/<path> with { "value": … }. The response is the v1 request envelope — { "state", "statusCode", "message", "href": "/signalk/v1/requests/<id>" }; poll href while state is PENDING. A path is only PUT-able if some plugin registered a handler for it (otherwise HTTP 405, "PUT not supported for <path>").
• History (v2): GET /signalk/v2/api/history/values?paths=<p1[:aggregate]>,… with from/to (ISO 8601 timestamps), duration (seconds, or an ISO 8601 duration like PT1H), and optional resolution. Answered by a history provider plugin (signalk-parquet, signalk-to-influxdb2, signalk-questdb, …); with none installed you get 501 {"error":"No history api provider configured"}.
• A v2 404 can mean "no provider", not "no API". Provider-backed routes mount per provider: with no resources provider, GET /signalk/v2/api/resources/waypoints is a plain 404; enable one and the same URL returns 200 {}. Autopilot routes behave the same. Only some APIs (history) exist unmounted-but-answering with a clean 501. Don't interpret 404 as "server too old".
• Conventions: _default targets the default device (…/autopilots/_default/engage), _providers / ?provider=<id> targets a specific provider, _config addresses API configuration. Multi-device and multi-provider APIs all follow these.
• Auth: with security disabled, the data and configuration routes above are open; with security enabled and allow_readonly on (the common setup), reads stay anonymous. Writes and protected reads need a token: POST /signalk/v1/auth/login with { "username", "password" }, then send it as a Bearer header (REST) or let the cookie ride (browser + WebSocket). Everything under /skServer/* and /plugins/* is admin — that's server-configuration surface, not data.
• "Security disabled" is not "everything open" — applicationData inverts it. /signalk/v1/applicationData/{global,user}/… is per-user/per-app storage, so it is disabled when security is off rather than unguarded: the interface sees securityStrategy.isDummy() and returns early, registering only POST handlers that answer 405 security is not enabled. The GET handlers are never registered at all on that path, so reads fall through to a plain 404 rather than a 405. Enable security and both appear, global behind admin-write and user behind write. Verified in signalk-server 2.30.0+ (src/interfaces/applicationData.js).