Web API - Overview

HomeGenie RESTful web services are based on a dual model. One is the commonly used synchronous request/response model, where the client calls a web service command and get a response from the server right after. The other one is an asynchronous model where the client calls a web service command that will cause an event to be fired and that will be observable through the real-time HomeGenie Event Stream. So the client in order to acknowledge that the issued command led to the expected action, it has to listen to the event stream.

HomeGenie Web UI

A good client example using the asynchronous model is the HomeGenie web UI itself, where most UI components (as widgets) use the MVC approach implemented through the event stream.

Common API syntax

The following is the commonly used syntax in an HomeGenie web service call: 

/api/<module_domain>/<module_address>[/<module_section>]/<command>[/<option_1>/.../<option_n>]

Where <module_domain> is used to address a specific api domain, <module_address> the target module of the API <command> and <option_1>...<option_n> are optional parameters that the <command> may require.

To get the list of interfaces enabled in HomeGenie, we will invoke the Interfaces.List command of the Config module in HomeGenie Core API which domain is HomeAutomation.HomeGenie.

/api/HomeAutomation.HomeGenie/Config/Interfaces.List

In the above example we also see that a <command> is commonly formed by two words separted by a dot. The first word "Interfaces" is the command domain and the second word "List" is the command itself.