device_id Routing
In protocol v2.0, every per-device endpoint takes device_id as a query parameter.
Why Query Parameters?
In v1.0, device IDs were embedded in the URL path (/devices/{id}/status). This caused issues:
- Adapters needed complex routing logic
- Multi-device adapters required path-based multiplexing
- URL patterns were inconsistent across adapters
In v2.0, the device_id is a query parameter on a flat endpoint:
GET /status?device_id=ada-58b6b21b
POST /action?device_id=ada-58b6b21b
GET /ui?device_id=ada-58b6b21b
Adapter-Level vs Device-Level
| Endpoint | Level | device_id Required? |
|---|---|---|
/ping | Adapter | No |
/capabilities | Adapter | No |
/status | Device | Yes |
/action | Device | Yes |
/ui | Device | Yes |
/webhook/register | Device | Yes |
Full URL Example
https://space-os.tailc029f9.ts.net/status?device_id=ada-58b6b21b-door-9728
The adapter endpoint URL registered in ZenEdge already includes the device_id:
https://space-os.tailc029f9.ts.net?device_id=ada-58b6b21b
Next Steps
- Criticality Tiers — Failure handling
- Capability Discovery — Device declarations