RoboHub

This page was generated from the source of RoboHub. Edit the source, not this page.

Application API

What an application offers other applications, the keeper and external clients:
a small read-only REST API, the same in every RoboHub application. It is not a
gateway — it has no projects, devices or actions — but it serves more than the
application received from its gateway: the values it derives, the values it
computes itself, and the readings it chooses to pass on, each with its history,
and its journal. appshell's settings page names these paths on its about tab.

How an application uses it

Include the module after inventory and journal, and add it to deps. It
brings the robohub.gateway interface only, for the history a derived value is
computed from; an application that binds no gateway still serves what it
publishes. The module needs no host hooks. The application:

  • reads its presets/api.yml at startup with appapi_presets(text);
  • calls appapi_tick() from its background work, about once a minute — it
    computes every derived and exported value, keeps it, and drops history older
    than 30 days;
  • publishes what it computes itself with appapi_publish(id, value, unit, label)
    (energy's site balance, a tank's stocking level);
  • answers rules_host_value with appapi_value(id), so a rule can name a
    derived value (aquarium.days_since_water_change).

appapi_summary(series) reads a gateway series into its count, sum, lowest,
highest, last value and integral, for an application that computes from history
itself.

Values

KindWhere it comes from
derivedthe application's presets/api.yml, computed by appapi_tick()
publishedthe application's own code: appapi_publish(id, value, unit, label)
exportan inventory item's reading it passes on (fn: export)
# presets/api.yml
values:
  temperature_avg_24h:
    from: heater.temperature
    fn: avg
    window: 24h
    unit: °C
    label: Water temperature, 24 h average
  days_since_water_change:
    from: water_change
    fn: since
    unit: d
  heater_energy_month:
    from: heater.power
    fn: integral
    window: 30d
    unit: Wh
  heater_temperature:
    from: heater.temperature
    fn: export
    unit: °C

from is an inventory item's capability by handle, or for since a journal kind
(kind or kind.subject). fn is latest, avg, min, max, integral (over
time: watts become watt-hours), since (days since the newest journal entry of
that kind) or export. appapi_presets(text) reads the file; appapi_value(id)
is a value's newest text, which is what a host answers a rule with.

Endpoints

PathAnswers
GET /api/v1/values{"application":"aquarium","values":[{"id","value","unit","label","kind","updated_at"}]}
GET /api/v1/values/{id}one value
GET /api/v1/values/{id}/history?from=&to={"ok":true,"points":[{"t":ms,"v":value}]}, the gateway's own shape; the last day by default
GET /api/v1/events?since=&level=&kind=the journal, as the journal module serves it

The paths are read-only, so a person or token with only the application's
<app>:read grant at the keeper reaches them. History is kept for 30 days.

Data it keeps

In the application's database, <workspace>/data/app.db (or RHO_APPAPI_DB),
from the module's own db/schema.sql:

TableWhat it holds
appapi_valuesEach value's newest text, unit, label, kind and when it was updated
appapi_historyEvery value kept, for 30 days
appapi_derivedThe derived and exported values the presets declare

The module has no settings; what it derives is the application's
presets/api.yml.

Reference

Generated from the module's manifest and sources when this site was built.

Exports — what an application may call (provides.exports, imported as robohub.appapi):

  • appapi_publish
  • appapi_value
  • AppapiSummary
  • appapi_summary
  • appapi_tick
  • appapi_presets

Routes — registered on the host application's router:

MethodPathHandler
GET/api/v1/valuesappapi_values_api
GET/api/v1/values/{id}appapi_value_api
GET/api/v1/values/{id}/historyappapi_history_api
GET/api/v1/eventsappapi_events_api

Release history

[0.1.0] - 2026-11-13

The read-only REST API every RoboHub application offers in the same shape: values derived from its presets (latest, avg, min, max, integral over a window from the gateway's history, days since a journal event, exported readings), values it publishes from its own code, each with 30 days of history, and its journal. /api/v1/values, /values/{id}, /values/{id}/history in the gateway's point shape, and /api/v1/events.

[0.1.1] - 2026-11-13

The clock is read from the process (rho_now_s, rho 0.6.0) instead of from date written to a file and read back, which a request and the background loop could truncate under each other: entries dated 1970 and modes that expired at once.

[0.1.2] - 2026-11-13

A value's history returns the newest 5000 points of its window rather than the oldest, and each value to the nearest thousandth (0.007 was 0.006).

[0.1.3] - 2026-11-14

Trimming, URL escapes, form fields and decimals come from the toolchain (rho 0.7.0: str_trim, str_url_encode/str_url_decode, form_field, milli_*) rather than this module's own copy, the same on both backends. Needs rho 0.7.0. A value is read with a decimal comma as well as a dot.

[0.1.4] - 2026-11-14

appapi_value — a rule's host value and every dashboard card that shows one — looks the value up by its id, where it listed every value. ignore_appapi is appapi_ignore.

[0.1.5] - 2026-11-14

Its data is kept where app_workspace() says (rho 0.8.0) — the application's workspace, else ~/.rho/apps/<app> — so two applications started by hand no longer share this module's records. Copies of helpers the toolchain now provides (i64_to_str, str_lower, str_field, json_str_field, escape_html) are gone. Needs rho 0.8.0.

[0.2.0] - 2026-11-14

It lists what other code may use (provides.exports, imported as robohub.appapi). An application that includes it still reaches everything, and a build (rho 0.8.3) names each call to a function outside the list. The list is what the applications and modules of the ecosystem call; anything else is the module's own and may change without notice.