Skip to end of metadata
Go to start of metadata

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

The Sky Cloud API is usually used in tandem with the Sky Event API

URL Format

The format of the Sky Cloud API is as follows:

  https://cs.kobj.net/sky/cloud/<rid>/<function>?name0=value0&...&namen=valuen

Where

  • <rid> - The ruleset ID or alias of the module
  • <function> - The name of the function in the module
  • name0, value0 - 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 Cloud URL formatted as previously shown will return the JSON result of calling <function> in the module named <rid> with the given parameters. The content type of the return is application/json

Authorization an Event Channel

The API has to be run against an event channel that ties it to a specific personal cloud or pico. 

OAuth is required for using Sky Cloud API. The details of setting up OAuth for use with a personal cloud are documented here

As part of the OAuth interaction you will receive and ECI. You should have stored this in your system since the ECI will be used for Sky Cloud API calls. 

The preferred way to use the ECI is to put it in the Kobj-Session header when making the GET request. 

If you cannot place the ECI in a header due to limitation on the calling side, it can be placed in the _eci parameter in the URL query string.

All Sky Cloud API requests should be made over SSL to protect the credentials. 

Preparing a Module for Use with Sky Cloud

Any module can be used with the Sky Cloud API. In order to use a module with Sky Cloud, the sharing pragma in the meta section of the ruleset must be "on". 

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

Note that you can only run functions. So if you want to return a constant, you have to 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. 

Aliases

The following CloudOS modules have aliases that can be used in place of the <rid> in the URL. 

AliasRID
pdsa169x676
cloudosa169x625
notifya16x161
squaretaga41x178
mythingsa169x667
pdsxa369x202

Error Codes

The following errors will be returned in the JSON response:

CodeMeaning

100

Sharing not on for module 
101Function does not exist
102Module not installed for user
103No ECI defined

Example

Suppose that you had defined the following function:

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

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

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

 

 

Labels: