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.

Troubleshooting HTTP API Requests

It is better to use curl or a similar Linux tool from the command line to form and debug HTTP request URLs than it is to use a browser. You can use a browser to try a request, but if you are getting an error or unexpected result, switching to curl will provide more information — browsers tend to "water down" the details of HTTP errors.

Here are some general steps to take when troubleshooting:

  1. First, always verify connectivity. The simplest request is the alive request (http://ip:8111/api/v1/alive). If Reactor is up and running, this will always produce a result with no parameters. If you can't complete this test, either Reactor is not running, or the IP or port you are trying to access isn't available in the configuration.
  2. If you get an error code 404 with a Not Found message, that means either you have entered the IP URL incorrectly, or the object you are trying to access (rule, reaction, etc.) cannot be found.
  3. Try a simpler request for the object. For example, if you are trying to do a perform request to run an action on an entity, but getting an error, try running just the query for the entity and make sure it can return a correct result: http://ip:8111/api/v1/entity/id
  4. If you are getting a 400 or 500 error code, possibly with a Request failed message, check the Reactor log file. Find the lines with httpapi identified as the subsystem. The error here will often be sufficient to help you correct your URL or parameters. You may need to look above and below the matching lines to see the full context of the message.
  5. If you need to post on the SmartHome Community for help, remember to follow the posting guidelines -- show your work, give all the details up front. The more effort you put in to asking your question, the more likely someone will put in the effort to help and the quicker they can answer without a lot of back and forth.

Updated 2022-Nov-28