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.ymlat startup withappapi_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_valuewithappapi_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
| Kind | Where it comes from |
|---|---|
derived | the application's presets/api.yml, computed by appapi_tick() |
published | the application's own code: appapi_publish(id, value, unit, label) |
export | an 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
| Path | Answers |
|---|---|
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:
| Table | What it holds |
|---|---|
appapi_values | Each value's newest text, unit, label, kind and when it was updated |
appapi_history | Every value kept, for 30 days |
appapi_derived | The 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_publishappapi_valueAppapiSummaryappapi_summaryappapi_tickappapi_presets
Routes — registered on the host application's router:
| Method | Path | Handler |
|---|---|---|
| GET | /api/v1/values | appapi_values_api |
| GET | /api/v1/values/{id} | appapi_value_api |
| GET | /api/v1/values/{id}/history | appapi_history_api |
| GET | /api/v1/events | appapi_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.