Sky Query API

The Sky Query API gives access to data in picos. Sky Query defines a meta API since the actual specific features of the API depend on the KRL module that is referenced in the Sky Query URL. In essence, the Sky Query API is extensible by any KRL developer.

The Sky Query API is usually used in tandem with the Sky Event API.

1 URL Format
2 API Action
3 Preparing a Module for Use with Sky Query
4 Example

URL Format

The format of the Sky Query API is as follows:

The schema can be either http or https, depending on the configuration of the server hosting the picos.

The domain name is the domain name of the pico-engine hosting the picos processing the events.

The path is formatted as follows:

/sky/Query/<eci>/<rid>/<function>?name0=value0&...&nameN=valueN

Where

<eci> - The ECI of the pico
<rid> - The ruleset ID or alias of the module. If the module is not installed on the pico, a JSON object is returned with an error field and an error message containing <rid>.
<function> - The name of the function in the module
name₀, value₀ - The parameters to the function. The names must match the parameters names in the module definition. Order is not important.

API Action

Performing an HTTP GET request on a Sky Query URL formatted as previously shown will return a string with the JSON result of calling <function> in the module named <rid> with the given parameters. The content type of the return is application/json.

Preparing a Module for Use with Sky Query

Any module can be used with the Sky Query API. InTose a module with Sky Query, the shares pragma in the meta section of the ruleset must list the names of the functions that are shared (and thus callable by Sky Query).

meta {
  name "thermostat module"
  shares mode, get_temperature
}

Any function (and only functions) in the shares list of the module can be called using Sky Query.

Note that you can only run functions. So if you want to return a constant, you can wrap it in a parameterless function.

The names of the parameters to the function will be the names that are used in the GET request query string, so picking good names for your function parameters will ensure that the API represented by your module will be more usable.

Example

Suppose that you had defined the following function:

ruleset a16x55 {
  meta {
    name "thermostat module"
    shares get_mode, get_temperature
  }
  global {
    get_mode = function() {
      ...
    }
    get_temperature = function(room) {
      ...
    }
}

You could call the get_temperature() function, supplying bedroom as the parameter with the following request:

GET /sky/Query/a16x55/get_temperature?room=bedroom

You would get back a string with a JSON response. The contents of the response depend on the specific operation of the get_temperature() function.