Skip to content

http-api.md

Latest commit

 

History

History
206 lines (147 loc) · 4.08 KB

http-api.md

File metadata and controls

206 lines (147 loc) · 4.08 KB

Runtime HTTP API (v0)

Human-oriented runtime API guide.

Machine contract authority:

  1. OpenAPI: schemas/http/runtime-http.openapi.v0.yaml
  2. Contract examples: tests/contracts/runtime-http/examples/
  3. Baseline: docs/contracts/runtime-http-baseline.md

Use this file for operational semantics and practical examples.

Transport

  1. Base URL default: http://127.0.0.1:8080
  2. JSON content type: application/json
  3. API prefix: /v0
  4. No auth model in v0

CORS behavior comes from runtime config (http.cors_*).

Common Response Envelope

All JSON responses include status:

{
  "status": {
    "code": "OK",
    "message": "ok"
  }
}

Common status-code mapping:

Code HTTP
OK 200
INVALID_ARGUMENT 400
NOT_FOUND 404
FAILED_PRECONDITION 409
UNAVAILABLE 503
DEADLINE_EXCEEDED 504
INTERNAL 500

Endpoint Map

Runtime and provider status

  1. GET /v0/runtime/status - high-level runtime/provider summary.
  2. GET /v0/providers/health - per-provider lifecycle/supervision and device health.

Discovery and capabilities

  1. GET /v0/devices
  2. GET /v0/devices/{provider_id}/{device_id}/capabilities

State reads

  1. GET /v0/state
  2. GET /v0/state/{provider_id}/{device_id} (supports repeated signal_id filters)

Control

  1. POST /v0/call

Notes:

  1. Request currently requires function_id.
  2. Args use typed ADPP value encoding.

Automation and parameters

  1. GET /v0/mode
  2. POST /v0/mode
  3. GET /v0/parameters
  4. POST /v0/parameters
  5. GET /v0/automation/tree
  6. GET /v0/automation/status

Streaming

  1. GET /v0/events (SSE)

Optional query filters:

  1. provider_id
  2. device_id
  3. signal_id

Current event names:

  1. state_update
  2. quality_change
  3. device_availability
  4. mode_change
  5. parameter_change
  6. bt_error
  7. provider_health_change

Typed Value Encoding

ADPP value payload format:

Type Example
double {"type":"double","double":1.23}
int64 {"type":"int64","int64":-42}
uint64 {"type":"uint64","uint64":42}
bool {"type":"bool","bool":true}
string {"type":"string","string":"AUTO"}
bytes {"type":"bytes","base64":"AAECAw=="}

Quality Semantics

Signal quality values:

  1. OK
  2. STALE
  3. UNAVAILABLE
  4. FAULT

Device-level quality is computed as worst signal quality.

Practical Examples

Runtime status

curl -s http://127.0.0.1:8080/v0/runtime/status | jq

Providers health

curl -s http://127.0.0.1:8080/v0/providers/health | jq

Devices + capabilities

curl -s http://127.0.0.1:8080/v0/devices | jq
curl -s http://127.0.0.1:8080/v0/devices/sim0/motorctl0/capabilities | jq

State

curl -s http://127.0.0.1:8080/v0/state | jq
curl -s "http://127.0.0.1:8080/v0/state/sim0/motorctl0?signal_id=motor1_duty" | jq

Call device function

curl -s -X POST http://127.0.0.1:8080/v0/call \
  -H "Content-Type: application/json" \
  -d '{
    "provider_id": "sim0",
    "device_id": "motorctl0",
    "function_id": 10,
    "args": {
      "motor_index": {"type": "int64", "int64": 1},
      "duty": {"type": "double", "double": 0.75}
    }
  }' | jq

Mode and parameters

curl -s http://127.0.0.1:8080/v0/mode | jq
curl -s -X POST http://127.0.0.1:8080/v0/mode \
  -H "Content-Type: application/json" \
  -d '{"mode":"MANUAL"}' | jq

curl -s http://127.0.0.1:8080/v0/parameters | jq
curl -s -X POST http://127.0.0.1:8080/v0/parameters \
  -H "Content-Type: application/json" \
  -d '{"name":"temp_setpoint","value":30.0}' | jq

SSE stream

curl -N http://127.0.0.1:8080/v0/events

Error Payload

Example:

{
  "status": {
    "code": "NOT_FOUND",
    "message": "Device not found: sim0/nonexistent"
  }
}

Related

  1. docs/http/README.md - HTTP contract validation workflow.
  2. tests/contracts/runtime-http/examples/manifest.yaml - fixture inventory.