API

General APIs structure

The GovOps framework exposes APIs which have the following general form:

GET http://HOST_ADDRESS:8080/APIManager/mapper/invoke/{deviceId}/{capabilityId}/{methodName}/{arguments}?arg1={first-argument}&arg2={second-argument}&...

• The HOST_ADDRESS is the IP address where the rtGovOps framework is deployed (This part is omitted in the examples below, but should be added when sending requests :)).

• deviceId - The Id of the managed device (as specified when the device first registers with rtGovOps). For example, in our cloud-based test bed the deviceId is the combination of the host machine IP and the port mapping to Docker container, e.g., 10.99.0.102:9080 (here 9080 maps to container's 80). The meta-information about the all available devices can be accessed via: GET.../APIManager/governanceScope/globalScope/ NOTE: Due to some encoding issues, always put the trailing "/".

• capabilityId - The Id of capability that needs to be invoked. The list of available capabilities in a device can be retrieved via: GET.../APIManager/mapper/invoke/{deviceId}/cManager/list/

• methodName - Since some of the capabilities expose multiple functions such as GET.../APIManager/mapper/{deviceId}/cStartStopSensor/[start|stop]), the exact function (method) that needs to be invoked is specified with the methodName.

• arguments - These are the HTTP request parameter and it is used for the capabilities which expect some input arguments such as GET.../APIManager/mapper/invoke/{deviceId}/cChangeSensorRate/update?interval=100

• Currently all the API calls return application/json.

The GovOps framework also supports working with generic governance scopes in order to enable flexible definitions within the governance processes without referencing individual devices. The general API call will have the following structure:

Working with generic governance scopes

GET http://HOST_ADDRESS:8080/APIManager/governanceScope/invokeScope/{predicates}/{capabilityId}/{methodName}/{arguments}?arg1={first-argument}&arg2={second-argument}&...

• predicats - The predicates are specified by supplying key/value pairs that need to be present in devices meta-data. As shown in the following example multiple key/value pair can be provided, by concatenating them with "&"
  type=FM5300&location=golfcourse-1.
• The rest of the path parameters have the same meaning as described in the previous section.

Working with uncertainty-aware GovOps APIs

GovOps supports configuring API invocations (to the underlying gateways) with uncertainty information. To configure a specific governance process with uncertainty considerations, you can do the following:

POST ... /APIManager/governanceScope/setProcessProps/{procId}
and pass the configuration parameters in body as JSON.

This should be called at the begging of each governance process and it will create a statefull configuration for the process with pocId, so that it can be reused for the subsequent requests by that process (See below how to pass the process ID).

The configuration should be passed in the body as JSON and the following options are available:

casheEnabled = "false";
tolerate_fault_percentage  = "50";
volume_per_circuit = "20";
run_in_isolation = "true";
fallback = "0";
time_before_fallback = "1000";
degree_parallelism = "200";
keep_alive = "5";

If the parameter is not specified a default value will be used.

Rough governance scopes are used to support working with governance scopes under uncertainty (e.g., missing data). GovOps implements a custom algorithm to handle the data-related uncertainty. The most important configuration options are:

missing_data = "arrtName1=[?|*|-] & arrtName2=[?|*|-] [&] ..."
selection_strategy = "pessimistic|optimistic"

which should be passed for each request that needs to calculate a governance scope. For example, one can invoke

POST ... APIManager/governanceScope/invokeScope/{procId}/{query}/{capaId}/{method}
passing the above config parameters in body as JSON  e.g.,
{"missing_data":"location=*&owner=?", "selection_strategy":"optimistic"}

The procId is the aforementioned process ID and the other parameters are the same as described in the previous section.