Path/Prefix

All HTTP APIs are accessible at the service IP and port beneath the /api/v1/ path on the host system (i.e. http://192.168.0.10:8111/api/v1/alive).

There is no security/authorization currently, but this is expected to change.

API Conventions

Except where indicated, all APIs return a JSON structure. Generally, data-requesting APIs return their data unwrapped. That is, there is no surrounding structure giving the status of the request in addition to the response data: if you get data, it's good. HTTP errors (400, 404, etc.) are returned in preference to giving a valid HTTP reply containing an error structure. In the few APIs where data is not returned, an object with status field containing a boolean value is returned.

All timestamps in returned data are integer milliseconds since the Epoch (that is, they are JavaScript timestamps).

All charset encoding is UTF-8.

Some of you may notice that the HTTP PUT method is used for several APIs, and POST is not supported. This API follows the convention of RFC2616, which regards the PUT method as idempotent, where POST is not. Essentially it is a best practice for REST APIs, though not many follow it in my experience.

Documentation Conventions

Within the URLs given in this documentation, named parameters are indicated by : followed by the name; for example, capability/:id means that a capability ID/name is expected to follow the slash after the word capability in the URL, so fetching the definition of the power_switch capability would be done with the full URL http://host-ip:8111/api/v1/capability/power_switch. Notice that the : is not part of the final URL.

Updated 2022-May-21