Horizon APIs

This document contains the Horizon REST APIs for the Horizon agent running on an edge node. The output of the APIs is in JSON compact format. To get a better view, you can use the JSONView extension in your web browser or use the jq command from the command line interface. For example:

curl -s http://<ip>/status | jq '.'

1. Horizon Agent

API: GET /status

Get the connectivity, and configuration, status on the node. The output includes the status of the agent configuration and the node’s connectivity.

Parameters

none

Response

code:

200 – success

body:

name	subfield	type	description
configuration		json	the configuration data.
	exchange_api	string	the url for the exchange being used by the Horizon agent.
	exchange_version	string	the current version of the exchange being used.
	required_minimum_exchange_version	string	the required minimum version for the exchange.
	preferred_exchange_version	string	the preferred version for the exchange in order to use all the Horizon functions.
	mms_api	string	the url for the model management system.
	architecture	string	the hardware architecture of the node as returned from the Go language API runtime.GOARCH.
	horizon_version	string	The current version of the horiozn running on this node.
connectivity		json	whether or not the node has network connectivity with some remote sites.

Example

curl -s http://localhost:8510/status | jq '.'
{
  "configuration": {
    "exchange_api": "http://exchange-api:8080/v1/",
    "exchange_version": "2.15.1",
    "required_minimum_exchange_version": "2.15.1",
    "preferred_exchange_version": "2.15.1",
    "mms_api": "https://css-api:9443",
    "architecture": "amd64",
    "horizon_version": "2.24.5"
  },
  "liveHealth": null
}

API: GET /status/workers

Get the current Horizon agent worker status and the status trasition logs.

Parameters

none

Response

code:

200 – success

body:

name	subfield	type	description
workers		json	the current status of each worker and its subworkers.
	name	string	the name of the worker.
	status	string	the status of the worker. The valid values are: added, started, initialized, initialization failed, terminating, terminated.
	subworker_status	json	the name and the status of the subworkers that are created by this worker.
worker_status_log		string array	the history of the worker status changes.

Example

curl -s  http://localhost:8510/status/workers | jq
{
  "workers": {
    "AgBot": {
      "name": "AgBot",
      "status": "terminated",
      "subworker_status": {}
    },
    "Agreement": {
      "name": "Agreement",
      "status": "initialized",
      "subworker_status": {}
    },
    "Container": {
      "name": "Container",
      "status": "initialized",
      "subworker_status": {}
    },
    "ExchangeChanges": {
      "name": "ExchangeChanges",
      "status": "initialized",
      "subworker_status": {}
    },
    "ExchangeMessages": {
      "name": "ExchangeMessages",
      "status": "initialized",
      "subworker_status": {}
    },
    "Governance": {
      "name": "Governance",
      "status": "initialized",
      "subworker_status": {
        "ContainerGovernor": "started",
        "MicroserviceGovernor": "started",
        "SurfaceExchErrors": "started"
      }
    },
    "ImageFetch": {
      "name": "ImageFetch",
      "status": "initialized",
      "subworker_status": {}
    },
    "Kube": {
      "name": "Kube",
      "status": "initialized",
      "subworker_status": {}
    },
    "Resource": {
      "name": "Resource",
      "status": "initialized",
      "subworker_status": {}
    }
  },
  "worker_status_log": [
    "2020-03-27 19:06:07 Worker AgBot: started.",
    "2020-03-27 19:06:07 Worker AgBot: initialization failed.",
    "2020-03-27 19:06:07 Worker Agreement: started.",
    "2020-03-27 19:06:07 Worker Governance: started.",
    "2020-03-27 19:06:07 Worker ExchangeMessages: started.",
    "2020-03-27 19:06:07 Worker ExchangeMessages: initialized.",
    "2020-03-27 19:06:07 Worker Container: started.",
    "2020-03-27 19:06:07 Worker AgBot: terminated.",
    "2020-03-27 19:06:07 Worker ImageFetch: started.",
    "2020-03-27 19:06:07 Worker ImageFetch: initialized.",
    "2020-03-27 19:06:07 Worker Kube: started.",
    "2020-03-27 19:06:07 Worker Kube: initialized.",
    "2020-03-27 19:06:07 Worker Resource: started.",
    "2020-03-27 19:06:07 Worker Resource: initialized.",
    "2020-03-27 19:06:07 Worker ExchangeChanges: started.",
    "2020-03-27 19:06:07 Worker ExchangeChanges: initialized.",
    "2020-03-27 19:06:07 Worker Container: initialized.",
    "2020-03-27 19:06:12 Worker Agreement: initialized.",
    "2020-03-27 19:19:32 Worker Governance: subworker SurfaceExchErrors added.",
    "2020-03-27 19:19:32 Worker Governance: subworker ContainerGovernor added.",
    "2020-03-27 19:19:32 Worker Governance: subworker MicroserviceGovernor added.",
    "2020-03-27 19:19:32 Worker Governance: subworker SurfaceExchErrors started.",
    "2020-03-27 19:19:32 Worker Governance: subworker ContainerGovernor started.",
    "2020-03-27 19:19:32 Worker Governance: subworker MicroserviceGovernor started.",
    "2020-03-27 19:19:32 Worker Governance: initialized."
  ]
}

2. Node

API: GET /node

Get the Horizon platform configuration of the Horizon agent. The configuration includes the agent’s exchange id, organization, configuration state, and whether or not the agent is using a pattern configuration.

Parameters

none

Response

code:

200 – success

body:

name	type	description
id	string	the agent’s unique exchange id.
organization	string	the agent’s organization.
pattern	string	the pattern that will be deployed on the node.
name	string	the user readable name for the agent.
nodeType	string	the node type. Valid values are ‘device’ and ‘cluster’.
token_valid	bool	whether the agent’s exchange token is valid or not.
token_last_valid_time	uint64	the time stamp when the agent’s token was last valid.
ha_group	string	the name of the HA group that node is in.
configstate	json	the current configuration state of the agent. It contains the state and the last_update_time. The valid values for the state are “configuring”, “configured”, “unconfiguring”, and “unconfigured”.

Example

curl -s http://localhost:8510/node | jq '.'
{
  "id": "myvs1",
  "organization": "mycompany",
  "pattern": "netspeed-amd64",
  "name": "mydevice",
  "nodeType": "device",
  "token_last_valid_time": 1508174346,
  "token_valid": true,
  "ha_group": "mygroup",
  "configstate": {
    "state": "configured",
    "last_update_time": 1508174348
  }
}

API: POST /node

Configure the Horizon agent. This API assumes that the agent’s node has already been registered in the exchange. The configstate of the agent is changed to “configuring” after calling this API.

Parameters

body:

name	type	description
id	string	the agent’s unique exchange id.
token	string	the agent’s authentication token for the exchange.
organization	string	the agent’s organization.
pattern	string	the pattern that will be deployed on the node.
name	string	the user readable name for the agent.

Response

code:

201 – success

Example

curl -s -w "%{http_code}" -X POST -H 'Content-Type: application/json'  -d '{
      "id": "mydevice",
      "organization": "mycompany",
      "pattern": "pat3",
      "name": "mydevice",
      "token": "dfjskjdsfkj"
    }'  http://localhost:8510/node

API: PATCH /node

Update the agent’s exchange token. This API can only be called when configstate is “configuring”.

Parameters

body:

name	type	description
id	string	the agent’s unique exchange id.
token	string	the agent’s authentication token for the exchange.

Response

code:

200 – success

Example

curl -s -w "%{http_code}" -X PATCH -H 'Content-Type: application/json'  -d '{
      "id": "mydevice",
      "token": "kj123idifdfjsklj"
    }'  http://localhost:8510/node

API: DELETE /node

Unconfigure the agent so that it can be re-configured. All agreements are cancelled, and workloads are stopped. The API could take minutes to send a response if invoked with block=true. This API can only be called when configstate is “configured” or “configuring”. After calling this API, configstate will be changed to “unconfiguring” while the agent quiesces, and then it will become “unconfigured”.

Parameters

name	type	description
block	bool	If true (the default), the API blocks until the agent is quiesced. If false, the caller will get control back quickly while the quiesce happens in the background. While this is occurring, the caller should invoke GET /node until they receive an HTTP status 404.
removeNode	bool	If true, the node’s entry in the exchange is also deleted, instead of just being cleared. The default is false.
deepClean	bool	If true, all the history of the previous registration will be removed. The default is false.

Response

code:

204 – success

body:

none

Example

curl -s -w "%{http_code}" -X DELETE "http://localhost:8510/node?block=true&removeNode=false"

API: GET /node/configstate

Get the current configuration state of the agent.

Parameters

none

Response

code:

200 – success

body:

name	type	description
state	string	Current configuration state of the agent. Valid values are “configuring”, “configured”, “unconfiguring”, and “unconfigured”.
last_update_time	uint64	timestamp when the state was last updated.

Example

curl -s http://localhost:8510/node/configstate | jq '.'
{
  "state": "configured",
  "last_update_time": 1510174292
}

API: PUT /node/configstate

Change the configuration state of the agent. The valid values for the state are “configuring” and “configured”. The “unconfigured” state is not settable through this API. The agent starts in the “configuring” state. You can change the state to “configured” after you have set the agent’s pattern through the /node API, and have configured all the service user input variables through the /service/config API. The agent will advertise itself as available for services once it enters the “configured” state.

Parameters

body:

name	type	description
state	string	the agent configuration state. The valid values are “configuring” and “configured”.

Response

code:

201 – success

body:

none

Example

curl -s -w "%{http_code}" -X PUT -H 'Content-Type: application/json'  -d '{
       "state": "configured"
    }'  http://localhost:8510/node/configstate

3. Attributes

API: GET /attribute

Get all the attributes for the edge node and registered services.

Parameters

none

Response

code:

200 – success

body:

name	type	description
attributes	array	an array of all the attributes for all the services. The fields of an attribute are defined in the following.

attribute

name	type	description
id	string	the id of the attribute.
label	string	the user readable name of the attribute
type	string	the attribute type. Supported attribute types are: MeteringAttributes, AgreementProtocolAttributes, UserInputAttributes, HTTPSBasicAuthAttributes, and DockerRegistryAuthAttributes.
publishable	bool	whether the attribute can be made public or not.
host_only	bool	whether or not the attribute will be passed to the service containers.
service_specs	array of json	an array of service organization and url. It applies to all services if it is empty. It is only required for the following attributes: MeteringAttributes, AgreementProtocolAttributes, UserInputAttributes.
mappings	map	a list of key value pairs.

Example

curl -s http://localhost:8510/attribute | jq '.'
{
  "attributes": [
    {
      "id": "f85de917-ecb1-4d65-9310-66b0d9d2642f",
      "type": "UserInputAttributes",
      "label": "User input variables",
      "publishable": false,
      "host_only": false,
      "service_specs": [
        {
          "url": "https://bluehorizon.network/services/weather",
          "organization": "e2edev"
        }
      ],
      "mappings": {
        "HZN_PWS_MODEL": "LaCrosse WS2317",
        "HZN_PWS_ST_TYPE": "WS23xx",
        "HZN_WUGNAME": "e2edev mocked pws",
        "MTN_PWS_MODEL": "LaCrosse WS2317",
        "MTN_PWS_ST_TYPE": "WS23xx"
      }
    }
  ]
}

API: POST /attribute

Parameters

body:

name	type	description
attribute	json	Please refer to Attribute Definitions for a description of all attributes.

Response

code:

201 – success

body:

none

Example

curl -s -w "%{http_code}" -X POST -H 'Content-Type: application/json' -d '{
  "type": "DockerRegistryAuthAttributes",
  "label": "Docker auth",
  "publishable": false,
  "host_only": true,
  "mappings": {
    "auths": [
      {
        "registry": "mydockerrepo", username": "user1", "token": "myDockerhubPassword"
      },
      {
        "registry": "registry.ng.bluemix.net", "username": "token", "token": "myDockerToken"
      }
    ]
  }
}'  http://localhost:8510/attribute

API: GET /attribute/{id}

Get the attribute with the given id

Parameters

none

Response

code:

200 – success

body:

name	type	description
id	string	the id of the attribute.
label	string	the user readable name of the attribute
type	string	the attribute type. Supported attribute types are: MeteringAttributes, AgreementProtocolAttributes, UserInputAttributes, HTTPSBasicAuthAttributes, and DockerRegistryAuthAttributes.
publishable	bool	whether the attribute can be made public or not.
host_only	bool	whether or not the attribute will be passed to the service containers.
service_specs	array of json	an array of service organization and url. It applies to all services if it is empty. It is only required for the following attributes: MeteringAttributes, AgreementProtocolAttributes, UserInputAttributes.
mappings	map	a list of key value pairs.

Example

curl -s -w "%{http_code}" http://localhost:8510/attribute/0d5762bf-67a6-49ff-8ff9-c0fd32a8699f | jq '.'
{
  "attributes": [
    {
      "id": "a784b89c-e6f7-46dc-bf39-f2ac812a70b4",
      "type": "UserInputAttributes",
      "label": "User input variables",
      "publishable": false,
      "host_only": false,
      "service_specs": [
        {
          "url": "https://bluehorizon.network/services/netspeed",
          "organization": "myorg"
        }
      ],
      "mappings": {
        "var1": "aString",
        "var2": 5,
        "var3": 10.2,
        "var4": [
          "abc",
          "123"
        ],
        "var5": "override"
      }
    }
  ]
}
200

API: PUT, PATCH /attribute/{id}

Modify an attribute for a service. If the service_specs is omitted, the attribute applies to all the services.

Parameters

body:

name	type	description
attribute	json	Please refer to the response body for the GET /attribute/{id} api for the fields of an attribute.

Response

code:

200 – success

body:

name	type	description
attribute	json	Please refer to the response body for the GET /attribute/{id} api for the fields of an attribute.

Example

curl -s -w "%{http_code}" -X PUT -d '{
      "id": "0d5762bf-67a6-49ff-8ff9-c0fd32a8699f",
      "type": "UserInputAttributes",
      "service_specs": [
        {
          "url": "https://bluehorizon.network/services/netspeed",
          "organization": "IBM"
        }
      ],
      "label": "app",
      "publishable": false,
      "host_only": false,
      "mappings": {
        "foo": "bar"
      }
    }' http://localhost:8510/attribute/0d5762bf-67a6-49ff-8ff9-c0fd32a8699f | jq '.'

API: DELETE /attribute/{id}

Modify an attribute for a service. If the service_specs is omitted, the attribute applies to all the services.

Parameters

none

Response

code:

200 – success

body:

name	type	description
attribute	json	Please refer to the response body for the GET /attribute/{id} api for the fields of an attribute.

Example

curl -s -w "%{http_code}" -X DELETE http://localhost:8510/attribute/0d5762bf-67a6-49ff-8ff9-c0fd32a8699f | jq '.'

4. Service

API: GET /service

Get the definition, the instance information and the configuration information for all the services.

Parameters

none

Response

code:

200 – success

body:

name	subfield	type	description
config		array of json	all the services and the associated configuration attributes. For the pattern case, these are the top level services and their dependent services the pattern references to. For the non-pattern case, thses are the registered dependent services and any top level services that use has configured.
definitions		json	the definition of all the related services.
	active	array of json	an array of service definitions that are actively in use. Please refer to the following table for the fields of a service definition object.
	archived	array of json	an array of service definitions that are archived. Please refer to the following table for the fields of a service definition object.
instances		json	the instances of all the running services. It contains the information about the running service containers.
	active	array of json	an array of service instances that are active. Please refer to the following table for the fields of a service instance object.
	archived	array of json	an array of service instances that are archived. Please refer to the following table for the fields of a service instance object.

service configuration:

name	subfield	type	description
sensor_url		string	the url of the service.
sensor_org		string	the organization of the service.
sensor_version		string	the version of the service.
auto_upgrade		boolean	if the service should be automatically upgraded when a new version becomes available.
active_upgrade		boolean	if the Horizon agent should actively terminate agreements when new versions become available (active) or wait for all the associated agreements terminated before making upgrade.
attributes		array of json	an array of attributes that are associated with the service.
	meta	json	the meta data for an attribute. It includes id, type, lable etc.
	{key1}	string	key value pairs to be used to configure the service.
	{key2}	string	key value pairs to be used to configure the service.

service definition:

name	subfield	type	description
record_id		string	the record id in the db.
owner		string	the owner of the service.
label		string	the user readable name of the service.
description		string	the discription of the service.
specRef		string	the url of the service.
organization		string	the organization of the service.
version		string	the version of the service.
arch		string	the architecture of the node the service can run on.
sharable		string	how the service containers are shared if there are mutiple services reference this service. The valid values are: singleton, mutiple and exlusice. “singleton” means that all the services can share a single instance of this service. “mutiple” means that each service should have its own instance of this service. “exclusive” means that there can only be one service that references this service on at ay time.
userInput		json	defines variables that can be configured by the user..
	name	json	the name of the variable.
	label	json	the user readable name of the variable.
	type	json	the data type of the variable.
	defaultValue	json	the default value of the variable. If it is set, then the user does not have to configure this variable.
public		boolean	whether the service can be refenced outside the organization.
requiredServices		array of json	an array of services that this service depends on.
	url	string	the url of the dependent service.
	org	string	the organization of the dependent service.
	version	string	the version of the dependent service.
	arch	string	of architecture of the dependent service.
deployment		string	how the service is deployed. It defines the containers, images and configurations for this service.
deployment_signature		string	the signature that can be used to verify the “deployment” string with a public key.
lastUpdated		string	date where the service is last update on the exchange.
archived		boolean	if the service definition is archived.
name		string	the name of the service.
requested_arch		string	the architecture from user input or from a service that refrences this service. It can be a synonym of the node architecture.
auto_upgrade		boolean	if the service should be automatically upgraded when a new version becomes available.
active_upgrade		boolean	if the Horizon agent should actively terminate agreements when new versions become available (active) or wait for all the associated agreements terminated before making upgrade.
upgrade_start_time		uint64	the time when the service upgrade is started.
upgrade_ms_unregistered_time		uint64	the time when the service is unregistered during the upgrade process.
upgrade_agreements_cleared_time		uint64	the time when all the associated agreements are cleared during the upgrade process.
upgrade_execution_start_time		uint64	the time when the new service is started running during the upgrade process.
upgrade_ms_reregistered_time		uint64	the time when the service is reregistered during the upgrade process.
upgrade_failed_time		uint64	the time when the service upgrade failed.
upgrade_failure_reason		uint64	the reason code for the service upgrade failure.
upgrade_failure_description		sting	the description for the service upgrade failure.
upgrade_new_ms_id		string	the record_id of the new service that this service is upgrading to.
metadata_hash		string	the hash for the service defined in the exchange.

service instance:

name	subfield	type	description
ref_url		string	the url of the service.
organization		string	the organization of the service.
version		string	the version of the service.
arch		string	the architecture of the node the service can run on.
instance_id		string	an unique id for this service instance.
archived		boolean	if the service instance is archived.
instance_creation_time		uint64	the time when the service instance is created.
execution_start_time		uint64	the time when the service containers are started.
execution_failure_code		uint64	the reason code for the service instance failure.
execution_failure_desc		sting	the description for the service instance failure.
cleanup_start_time		uint64	the time when the service instance is being cleaned.
associated_agreements		array of string	agreements that use this service instance.
microservicedef_id		string	record_id for the definiton of the service that this instance is for.
service_instance_path		array of array	the parent path of how to get to this service instance. Since there may be multiple services that depend on this service, there may be multiple paths.
	url	string	the url of the parent or grandparent service.
	org	string	the organization of the parent or grandparent service.
	version	string	the version of the parent or grandparent service.
agreement_less		boolean	if this service is a agreement-less service (as defined in the pattern).
max_retries		uint	maximum retries allowed.
max_retry_duration		uint	the number of seconds in which the specified number of retries must occur in order for next retry cycle.
current_retry_count		uint	the current retry count.
retry_start_time		uint64	the time when the service retry is started.
containers		json	the info for the running docker containers for this service.

Example

curl http://localhost:8510/service | jq '.config'
[
  {
    "sensor_url": "https://bluehorizon.network/services/netspeed",
    "sensor_org": "e2edev",
    "sensor_version": "2.3.0",
    "auto_upgrade": true,
    "active_upgrade": false,
    "attributes": [
      {
        "meta": {
          "id": "49cde8e2-a448-4f5e-98a1-c033deca5c53",
          "type": "UserInputAttributes",
          "label": "User input variables",
          "host_only": false,
          "publishable": false
        },
        "service_specs": [
          {
            "url": "https://bluehorizon.network/services/netspeed",
            "organization": "e2edev"
          }
        ],
        "mappings": {
          "var1": "aString",
          "var2": 5,
          "var3": 10.2,
          "var4": [
            "abc",
            "123"
          ],
          "var5": "override"
        }
      }
    ]
  },
  ...
]

curl http://localhost:8510/service | jq '.definitions.active'
[
  {
    "record_id": "1",
    "owner": "IBM/ibmadmin",
    "label": "Netspeed for x86_64",
    "description": "Netspeed service",
    "specRef": "https://bluehorizon.network/services/netspeed",
    "organization": "e2edev",
    "version": "2.3.0",
    "arch": "amd64",
    "sharable": "multiple",
    "downloadUrl": "",
    "matchHardware": {},
    "userInput": [
      {
        "name": "var1",
        "label": "",
        "type": "string",
        "defaultValue": ""
      },
      {
        "name": "var2",
        "label": "",
        "type": "int",
        "defaultValue": ""
      }
    ],
    "workloads": null,
    "public": true,
    "requiredServices": [
      {
        "url": "https://bluehorizon.network/services/network",
        "org": "myorg",
        "version": "1.0.0",
        "arch": "amd64"
      }
    ],
    "deployment": "{\"services\":{\"netspeed5\":{\"environment\":[\"MY_SETTINGS=0\"],\"image\":\"openhorizon/amd64_netspeed:2.5.0\"}}}",
    "deployment_signature": "vqwgYA/b",
    "lastUpdated": "2019-02-13T21:56:02.228Z[UTC]",
    "archived": false,
    "name": "netspeed",
    "requested_arch": "amd64",
    "upgrade_version_range": "[0.0.0,INFINITY)",
    "auto_upgrade": true,
    "active_upgrade": false,
    "upgrade_start_time": 0,
    "upgrade_ms_unregistered_time": 0,
    "upgrade_agreements_cleared_time": 0,
    "upgrade_execution_start_time": 0,
    "upgrade_ms_reregistered_time": 0,
    "upgrade_failed_time": 0,
    "upgrade_failure_reason": 0,
    "upgrade_failure_description": "",
    "upgrade_new_ms_id": "",
    "metadata_hash": "q8Lxbb/poHcq/+aDoFdAtF1PwCYXxfPWDjCEjm49Dc8="
  },
  ...
]

curl http://localhost:8510/service | jq '.instances.active'
[
  {
    "ref_url": "https://bluehorizon.network/services/location",
    "organization": "e2edev",
    "version": "2.0.6",
    "arch": "amd64",
    "instance_id": "535369111ae8d5d7c6dced904c0457f13c30b9ec6ed024fb53be649e4729c814",
    "archived": false,
    "instance_creation_time": 1550265488,
    "execution_start_time": 1550265501,
    "execution_failure_code": 0,
    "execution_failure_desc": "",
    "cleanup_start_time": 0,
    "associated_agreements": [
      "535369111ae8d5d7c6dced904c0457f13c30b9ec6ed024fb53be649e4729c814"
    ],
    "microservicedef_id": "2",
    "service_instance_path": [
      [
        {
          "url": "https://bluehorizon.network/services/location",
          "org": "e2edev",
          "version": "2.0.6"
        }
      ]
    ],
    "agreement_less": false,
    "max_retries": 0,
    "max_retry_duration": 0,
    "current_retry_count": 0,
    "retry_start_time": 0,
    "containers": [
      {
        "Id": "f9bca37e87e6128530902432b8cbb66dcd63e955b059e07ebc9b26f0266b9e63",
        "Image": "openhorizon/amd64_location:2.0.6",
        "Command": "/bin/sh -c /start.sh",
        "Created": 1550265500,
        "State": "running",
        "Status": "Up 2 days",
        "Names": [
          "/535369111ae8d5d7c6dced904c0457f13c30b9ec6ed024fb53be649e4729c814-location"
        ],
        "Labels": {
          "openhorizon.anax.agreement_id": "535369111ae8d5d7c6dced904c0457f13c30b9ec6ed024fb53be649e4729c814",
          "openhorizon.anax.deployment_description_hash": "tYE0SSJMmIjEH6wffMlFBP-qD_0=",
          "openhorizon.anax.service_name": "location",
          "openhorizon.anax.variation": ""
        },
        "NetworkSettings": {
          "Networks": {
            "535369111ae8d5d7c6dced904c0457f13c30b9ec6ed024fb53be649e4729c814": {
              "MacAddress": "02:42:c0:a8:70:02",
              "IPPrefixLen": 20,
              "IPAddress": "192.168.112.2",
              "Gateway": "192.168.112.1",
              "EndpointID": "c367b1de79cc87569c5b1b40c9c4a856f6f21dfea7e7b6766d58c08a829d6051",
              "NetworkID": "9a74f202ed8292a05ac06f7cc94186f69ab8455271a1dfc912c9bf8bb7859d59"
            },
             "e2edev_bluehorizon.network-services-locgps_2.0.4_22249248-9e92-470a-828d-da1875d5462c": {
              "MacAddress": "02:42:c0:a8:60:03",
              "IPPrefixLen": 20,
              "IPAddress": "192.168.96.3",
              "Gateway": "192.168.96.1",
              "EndpointID": "807817c5175a186f6e8de30ecd9291951b0538a19e389e37f9808d248f8b1a84",
              "NetworkID": "762d3afabd1cd20e25dc7bc15396ca07b8fd36dd6e2c25d10eed9e1a1ce9a8a9"
            }
          }
        },
        "Mounts": [
          {
            "Source": "/tmp/service_storage/535369111ae8d5d7c6dced904c0457f13c30b9ec6ed024fb53be649e4729c814",
            "Destination": "/service_config",
            "Mode": "rw",
            "RW": true
          }
        ]
      }
    ]
  },
  ...
]

API: GET /service/config

Get the service configuration for all services.

Parameters

none

Response

code:

200 – success

body: Please refer to the service configuration table of GET /service api for the field definitions.

Example

curl http://localhost:8510/service/config | jq
"config": [
  {
    "sensor_url": "https://bluehorizon.network/services/netspeed",
    "sensor_org": "e2edev",
    "sensor_version": "2.3.0",
    "auto_upgrade": true,
    "active_upgrade": false,
    "attributes": [
      {
        "meta": {
          "id": "49cde8e2-a448-4f5e-98a1-c033deca5c53",
          "type": "UserInputAttributes",
          "label": "User input variables",
          "host_only": false,
          "publishable": false
        },
        "service_specs": [
          {
            "url": "https://bluehorizon.network/services/netspeed",
            "organization": "e2edev"
          }
        ],
        "mappings": {
          "var1": "aString",
          "var2": 5,
          "var3": 10.2,
          "var4": [
            "abc",
            "123"
          ],
          "var5": "override"
        }
      }
    ]
  },
  ...
]

API: POST /service/config

Configure attributes for a service.

Parameters

body:

name	subfield	type	description
url		string	the url of the service to be configured.
organization		string	the organization of the service.
name		string	(optional) the name of the service.
arch		string	architecture of the service to be configured, could be a synonym. The default is the current node architecture.
versionRange		string	the version range of the service that the configuration applies to. The versionRange is in OSGI version format. The default is [0.0.0,INFINITY)
auto_upgrade		boolean	whether the service should be automatically upgraded or not when a new version becomes available. The default is true.
active_upgrade		boolean	whether the Horizon agent should actively terminate agreements or not when new versions become available (active) or wait for all the associated agreements terminated before making upgrade. The default is false.
attributes		array of json	an array of attributes that will be applied to the the service.
	type	string	the type of the attribute. Most commonly used type is UserInputAttributes.
	label	string	a short description for this configuration.
	publishable	bool	whether the attribute can be made public or not.
	host_only	bool	whether or not the attribute will be passed to the service containers.
	mappings	json	a list of name and value pairs of configuration data for the service.

Response

code:

200 – success

Example

read -d '' nsconfig <<EOF
{
  "url": "https://bluehorizon.network/services/netspeed",
  "versionRange": "2.2.0",
  "organization": "e2edev",
  "publishable": false,
  "host_only": false,
  "attributes": [
    {
      "type": "UserInputAttributes",
      "label": "User input variables",
      "publishable": false,
      "host_only": false,
      "mappings": {
        "var1": "bString",
        "var2": 10,
        "var3": 10.22,
        "var4": ["abcd", "1234"],
        "var5": "override2"
      }
    }
  ]
}
EOF

echo "$nsconfig" | curl -sS -X POST -H "Content-Type: application/json" --data @- http://localhost:8510/service/config

API: GET /service/configstate

Get the service configuration state for all services.

Parameters

none

Response

code:

200 – success

body:

name	subfield	type	description
configstates		array of json	an array of service configuration state.
	url	string	the url for the service.
	org	string	the organization for the service.
	configstate	string	the current configuration state for the service. The valid values are “active” and “suspended”.

Example

curl http://localhost:8510/service/configstate | jq
{
  "configstates": [
    {
      "url": "https://bluehorizon.network/services/netspeed",
      "org": "e2edev",
      "configState": "active"
    },
    {
      "url": "https://bluehorizon.network/service-cpu",
      "org": "e2edev",
      "configState": "suspended"
    },
   ...
  ]
}

API: POST /service/configstate

Configure attributes for a service.

Parameters

body:

name	type	description
url	string	the url of the service to be configured. If it is an empty string and the org is also an empty string, the new configuration state will apply to all the services. If it is an empty string and the org is not an empty string, the new configuration state will apply to all the services within the organization.
org	string	the organization of the service to be configured.
configstate	string	the new configuration state for the service.

Response

code:

200 – success

Example

curl -sS -X POST -H "Content-Type: application/json" --data '{"url": "myservice", "org": "myorg", "configstate": "suspended"}' http://localhost:8510/service/configstate

API: GET /service/policy

Get the current list of policies for each registered service.

Parameters

none

Response

code:

200 – success

body:

name	subfield	type	description
{policy name}		json	the name of a policy generated for a service.
	header	json	the header of the policy. It includes the name and the version of the policy.
	apiSpec	array	an array of api specifications. Each one includes a URL pointing to the definition of the API spec, the version of the API spec in OSGI version format, the organization that implements the API spec, whether or not exclusive access to this API spec is required and the hardware architecture of the API spec implementation.
	properties	array	an array of name value pairs that the current party have.
	agreementProtocols	array	an array of agreement protocols. Each one includes the name of the agreement protocol.

Note: The policy also contains other fields that are unused and therefore not documented.

Example

curl http://localhost:8510/service/policy | jq '.'
{
  "Policy for IBM_netspeed": {
    "header": {
      "name": "Policy for e2edev_netspeed",
      "version": "2.0"
    },
    "apiSpec": [
      {
        "specRef": "https://bluehorizon.network/services/netspeed",
        "organization": "e2edev",
        "version": "2.3.0",
        "exclusiveAccess": true,
        "arch": "amd64"
      }
    ],
    "valueExchange": {},
    "dataVerification": {
      "metering": {}
    },
    "proposalRejection": {},
    "properties": [
      {
        "name": "cpus",
        "value": "1"
      },
      {
        "name": "ram",
        "value": "1024"
      }
    ],
    "nodeHealth": {}
  },
  ...
]

5. Agreement

API: GET /agreement

Get all the active and archived agreements ever made by the agent. The agreements that are being terminated but not yet archived are treated as archived in this api.

Parameters

none

Response

code:

200 – success

name	subfield	type	description
name		string	the name of the policies used to make the agreement.
dependent_services		array of json	the organizations and urls of the services that the agreement workload depend on.
	url	string	the url for a service.
	organization	string	the organization for a service.
archived		bool	if the agreement is archived or not.
current_agreement_id		string	the id of the agreement.
consumer_id		string	the id of the agbot that proposed the agreement.
counterparty_address		string	the name of the agbot that proposed the agreement.
agreement_creation_time		uint64	the time when the agent received the agreement proposal from the agbot. The negotiation process starts.
agreement_accepted_time		uint64	the time when the agbot and the agent have come to agreement on the terms. Workload downloading starts.
agreement_finalized_time		uint64	the time when the agbot and the agent have finalized the agreement. Workloads are running and data is verified by the agbot.
agreement_execution_start_time		uint64	the time when the agent starts running the workloads.
agreement_data_received_time		uint64	the time when the agbot has verified that data was received from the workload.
agreement_terminated_time		uint64	the time when the agreement is terminated.
agreement_force_terminated_time		uint64	the time when the agreement is forced to be terminated by the Horizon agent initialization process.
terminated_reason		uint64	the reason code for the agreement termination.
terminated_description		string	the description of the agreement termination.
agreement_protocol_terminated_time		uint64	the time when the agreement protocol terminated.
workload_terminated_time		uint64	the time when the workload for an agreement terminated.
proposal		string	the proposal currently in effect.
proposal_sig		string	the proposal signature.
agreement_protocol		string	the name of the agreement protocol being used.
protocol_version		int	the version of the agreement protocol being used.
current_deployment		json	contains the deployment configuration for the workload. The key is the name of the workload and the value is the result of the /containers/<id> docker remote API call for the workload container. Please refer to the link for details.
extended_deployment		json	contains the deployment configuration for the cluster node. It contains the image and the operator for deploying a Kubernetes application.
metering_notification		json	the most recent metering notification received. It includes the amount, metering start time, data missed time, consumer address, consumer signature etc.
workload_to_run		json	the service to run for this agreement.
	url	json	the url of the service.
	org	json	the organization of the service.
	version	json	the version of the service.
	arch	json	the architecture of the edge node the service can run on.

Example

curl -s http://localhost:8510/agreement | jq '.'
{
  "agreements": {
    "active": [
      {
        "name": "Policy for netspeed merged with netspeed arm",
        "dependent_services": [
         {
            "url": "https://bluehorizon.network/services/locgps",
            "organization": "e2edev"
          }
        ],
        "archived": false,
        "current_agreement_id": "7539aad7bf9269c97bf6285b173b50f016dc13dbe722a1e7cedcfec8f23c528f",
        "consumer_id": "stg-agbot-lon02-01.horizon.hovitos.engineering",
        "counterparty_address": "76224dc349ce6a51728f32d0be3a33349bdd0680",
        "agreement_creation_time": 1481235346,
        "agreement_accepted_time": 1481235346,
        "agreement_finalized_time": 1481235492,
        "agreement_terminated_time": 0,
        "agreement_data_received_time": 1481235526,
        "agreement_execution_start_time": 1481235515,
        "current_deployment": {
          "netspeed5": {
            "config": {
              "Cpuset": "1-3",
              "Env": [
                "DEVICE_ID=00000000217597c7",
    ...
           ],
              "Cmd": null,
              "Image": "summit.hovitos.engineering/armhf/netspeed5:v1.8",
              "Volumes": {
                "/var/snap/bluehorizon/common/workload_ro/7539aad7bf9269c97bf6285b173b50f016dc13dbe722a1e7cedcfec8f23c528f": {}
              },
              "Entrypoint": null,
              "Labels": {
                "network.bluehorizon.colonus.agreement_id": "7539aad7bf9269c97bf6285b173b50f016dc13dbe722a1e7cedcfec8f23c528f",
                "network.bluehorizon.colonus.deployment_description_hash": "mE-GfPU0RkH6lSWPU0F1WPmpooU=",
                "network.bluehorizon.colonus.service_name": "netspeed5",
                "network.bluehorizon.colonus.variation": ""
              }
            },
            "host_config": {
              "Binds": [
                "/var/snap/bluehorizon/common/workload_ro/7539aad7bf9269c97bf6285b173b50f016dc13dbe722a1e7cedcfec8f23c528f:/workload_config:ro"
              ],
              "RestartPolicy": {
                "Name": "always"
              },
              "LogConfig": {
                "Type": "syslog",
                "Config": {
                  "tag": "workload-7539aad7bf9269c97bf6285b173b50f016dc13dbe722a1e7cedcfec8f23c528f_netspeed5"
                }
              }
            }
          }
        },
        "extended_deployment": null,
        "proposal"...",
        "proposal_sig": "174f67d343fcb0241e9bd8c01ef93f9cb17e1eb434f0234af6e5a3afcd227d93229bb97d26a2b9fae706aa3e5f2521a8dc48503405d682f319cc8925dcc3c34c01",
        "agreement_protocol": "Basic",
        "terminated_reason": 0,
        "terminated_description": ""
        "agreement_protocol_terminated_time": 0,
        "workload_terminated_time": 0,
        "metering_notification": {
            "amount": 42,
            "start_time": 1496257354,
            "current_time": 1496259896,
            "missed_time": 10,
            "consumer_meter_signature": "6955047f484573055a9a27b80c5f86daa9d6ae48ac...",
            "agreement_hash": "91a9099372ade4a41db26b0f27819d60080f7774d51e71dc026269c3ae86d727",
            "consumer_agreement_signature": "cf08e366c59b4e130a4f05d1921f3f56d899f...",
            "consumer_address": "0xc299ff03ff89b48c6e56c25bd6b53932b100f9d6",
            "producer_agreement_signature": "0ee94042d5c50e8773e23923e32826e4f01df...",
            "blockchain_type": "ethereum"
        }
      }
    ],
    "workload_to_run": {
      "url": "https://bluehorizon.network/services/netspeed",
      "org": "e2edev",
      "version": "2.0.6",
      "arch": "armhf"
    }
    "archived": []
  }
}

API: DELETE /agreement/{id}

Delete an agreement. The agbot will start a new agreement negotiation with the agent after the agreement is deleted.

Parameters

name	type	description
id	string	the id of the agreement to be deleted.

Response

code:

200 – success
404 – the agreement does not exist.

body:

none

Example

curl -X DELETE -s http://localhost:8510/agreement/a70042dd17d2c18fa0c9f354bf1b560061d024895cadd2162a0768687ed55533

6. Trusted Certs for Service Image Verification

API: GET /trust[?verbose=true]

Get the user stored x509 certificates for service container image verification.

Parameters

name	type	description
(query) verbose	string	(optional) parameter expands output type to include more detail about trusted certificates. Note, bare RSA PSS public keys (if trusted) are not included in detail output.

Response

code:

200 – success

body:

name	type	description
pem	json	an array of x509 certs or public keys (if the ‘verbose’ query param is not supplied) that are trusted by the agent. A cert can be trusted using the PUT method in an HTTP request to the trust/ path).

Example

curl -s http://localhost:8510/trust | jq  '.'
{
  "pem": [
    "Horizon-2111fe38d0aad1887dec4e1b7fb5e083fde3a393-public.pem",
    "LULZ-1e0572c9f28c5e9a0dafa14741665c3cfd80b580-public.pem"
  ]
}

Verbose output:

curl -s 'http://localhost:8510/trust?verbose=true' | jq  '.'
{
  "pem": [
    {
      "type": "KeyPairSimple",
      "serial_number": "1e:05:72:c9:f2:8c:5e:9a:0d:af:a1:47:41:66:5c:3c:fd:80:b5:80",
      "subject_names": {
        "commonName (CN)": "*",
        "organizationName (O)": "LULZ"
      },
      "have_private_key": false,
      "not_valid_before": "2018-01-15T13:09:00Z",
      "not_valid_after": "2022-01-16T01:08:58Z",
      "public_key": "-----BEGIN PUBLIC KEY-----\nMIICIjANBgkqhkiG9w0BAQ...",
      ...
    },
    ...
  ]
}

Retrieve RSA PSS public key from a particular enclosing x509 certificate suitable for shell redirection to a .pem file:

curl -s 'http://localhost:8510/trust?verbose=true' | jq -r '.pem[] | select(.serial_number == "1e:05:72:c9:f2:8c:5e:9a:0d:af:a1:47:41:66:5c:3c:fd:80:b5:80")'
-----BEGIN CERTIFICATE-----
MIIE5DCCAsygAwIBAgIUHgVyyfKMXpoNr6FHQWZcPP2AtYAwDQYJKoZIhvcNAQEL
BQAwGzENMAsGA1UEChMETFVMWjEKMAgGA1UEAxMBKjAeFw0xODAxMTUxMzA5MDBa
Fw0yMjAxMTYwMTA4NThaMBsxDTALBgNVBAoTBExVTFoxCjAIBgNVBAMTASowggIi
MA0GCSqGSIb3DQEBAQUAA4ICDwAwggIKAoICAQCe8yFhGf699+iDwoO+LRPSH4Ce
DICrG4SgFZ7/2/dGPduVmYUWGnu1Sb3lk1xEO+Wd4SJ3VvabzaAexgXUgup8bM2K
FbHi5BMbf3G4on+gdxdRwTriwX3UTXKj3+D47sGZS3j8tJrqTx58hhuR9qTaBzAh
rwhRtD1k7/NLIOCZ2xS5Tfb/mKgG378+xM5IQQ69P86fQN6V28qIYUIUIURRreE4
HjJAFXpkpdDYqPclt/91S+hOnc1fWJah5jXuxdrrZ2jNl/b5IDA4F2/dKbHJNBEL
3/9lg63USywzD6uP9OzB1Gkhyp6TrUHzQyBZU2kVH8Qx9Zz2eUeI5u7UmXMxEsXu
...
swRnEsXZy1Ssvmi9myJrKWc8GrkhotweVkAyAJFHJjusIR8Wm8lusZB2IFxwiuFI
NzGgG2JMPK4=
-----END CERTIFICATE-----

API: GET /trust/{filename}

Get the content of a trusted x509 cert from a file that has been previously stored by the agent.

Parameters

name	type	description
filename	string	the name of the x509 cert file to retrieve.

Response

code:

200 – success

body:

The contents of the requested file.

Example

curl -s http://localhost:8510/trust/Horizon-2111fe38d0aad1887dec4e1b7fb5e083fde3a393-public.pem > Horizon-2111fe38d0aad1887dec4e1b7fb5e083fde3a393-public.pem

API: PUT /trust/{filename}

Trust an x509 cert; used in service container image verification.

Parameters

name	type	description
filename	string	the name of the x509 cert file to upload.

Response

code:

200 – success

body:

none

Example

curl -T ~/.rsapsstool/keypairs/SomeOrg-6458f6e1efcbe13d5c567bd7c815ecfd0ea5459f-public.pem http://localhost:8510/trust/SomeOrg-6458f6e1efcbe13d5c567bd7c815ecfd0ea5459f-public.pem

API: DELETE /trust/{filename}

Delete an x509 cert from the agent; this is a revocation of trust for a particular certificate and enclosing RSA PSS key.

Parameters

name	type	description
filename	string	the name of the x509 cert file to remove.

Response

code:

204 – success

body:

none

Example

curl -s -X DELETE http://localhost:8510/trust/SomeOrg-6458f6e1efcbe13d5c567bd7c815ecfd0ea5459f-public.pem

7. Event Log

API: GET /eventlog

Get event logs for the Horizon agent for the current registration. It supports selection strings. The selections can be made against the attributes.

Parameters

none

Response

code:

200 – success

body:

name	type	description
record_id	string	the record id in the data base.
timestamp	uint64	the time when the event log was saved.
severity	string	the severity for this event. It can be ‘info’, ‘warning’ or ‘error’.
message	string	a human consumable the event message.
event_code	string	an event code that can be used by programs.
source_type	string	the source for the event. It can be ‘agreement’, ‘service’, ‘exchange’, ‘node’ etc.
event_source	json	a structure that holds the event source object.

Example

curl -s http://localhost:8510/eventlog | jq '.'
[
  {
    "record_id": "270",
    "timestamp": 1536861596,
    "severity": "info",
    "message": "Start node configuration/registration for node mynode1.",
    "event_code": "start_node_configuration_registration",
    "source_type": "node",
    "event_source": {
      "node_id": "5330a6eb4b177e9203a14d6780589f539f8ec809",
      "node_org": "mycomp",
      "pattern": "comp/netspeed",
      "config_state": ""
    }
  },
  {
    "record_id": "271",
    "timestamp": 1536861598,
    "severity": "info",
    "message": "Complete node configuration/registration for node mynode1.",
    "event_code": "node_configuration_registration_complete",
    "source_type": "node",
    "event_source": {
      "node_id": "mynode1",
      "node_org": "mycomp",
      "pattern": "netspeed",
      "config_state": "configured"
    }
  },
  {
    "record_id": "272",
    "timestamp": 1536861598,
    "severity": "info",
    "message": "Workload service containers for e2edev/https://bluehorizon.network/services/netspeed are up and running.",
    "event_code": "container_running",
    "source_type": "agreement",
    "event_source": {
      "agreement_id": "0a94bb0e85e2d98050cd89b5fc98ac3270462170ea836b1a91a2d2a01613c4f8",
       "workload_to_run": {
        "url": "https://bluehorizon.network/services/netspeed",
        "org": "e2edev",
        "version": "1.0",
        "arch": "amd64"
      },
      "dependent_services": [
        {
          "url": https://bluehorizon.network/services/gps",
          "organization": "e2edev"
      ],
      "consumer_id": "IBM/ag12345",
      "agreement_protocol": "Basic"
    }
  }
  ....
]

curl -s http://localhost:8510/eventlog?source_type=node&message=~Complete | jq '.'
[
  {
    "record_id": "271",
    "timestamp": 1536861598,
    "severity": "info",
    "message": "Complete node configuration/registration for node mynode1.",
    "event_code": "node_configuration_registration_complete",
    "source_type": "node",
    "event_source": {
      "node_id": "mynode1",
      "node_org": "mycomp",
      "pattern": "netspeed",
      "config_state": "configured"
    }
  }
]

API: GET /eventlog/all

Get all the event logs including the previous regstrations for the Horizon agent. It supports selection strings. The selections can be made against the attributes.

Parameters

none

Response

code:

200 – success

body:

name	type	description
record_id	string	the record id in the data base.
timestamp	uint64	the time when the event log was saved.
severity	string	the severity for this event. It can be ‘info’, ‘warning’ or ‘error’.
message	string	a human consumable the event message.
event_code	string	an event code that can be used by programs.
source_type	string	the source for the event. It can be ‘agreement’, ‘service’, ‘exchange’, ‘node’ etc.
event_source	json	a structure that holds the event source object.

Example

curl -s http://localhost:8510/eventlog/all | jq '.'
[
  {
    "record_id": "1",
    "timestamp": 1336861590,
    "severity": "info",
    "message": "Start node configuration/registration for node mynode1.",
    "event_code": "start_node_configuration_registration",
    "source_type": "node",
    "event_source": {
      "node_id": "mynode1",
      "node_org": "mycomp",
      "pattern": "mycomp/netspeed",
      "config_state": ""
    }
  },
  {
    "record_id": "2",
    "timestamp": 1336861600,
    "severity": "info",
    "message": "Complete node configuration/registration for node mynode1.",
    "event_code": "node_configuration_registration_complete",
    "source_type": "node",
    "event_source": {
      "node_id": "mynode1",
      "node_org": "mycomp",
      "pattern": "netspeed",
      "config_state": "configured"
    }
  },
  ....

8. Node User Input

API: GET /node/userinput

Get the node’s user input for the service configurations. The user input on the local node is alway in sync with the user input for the node on the exchange.

Parameters

none

Response

code:

200 – success

body:

name	type	description
serviceOrgid	string	the organization of the service.
serviceUrl	string	the url of the service.
serviceArch	string	the architecture of the service.
serviceVersionRange	string	the version range of the service that the configuration applies to. The serviceVersionRange is in OSGI version format. The default is [0.0.0,INFINITY).
inputs	json	an array of name and value pairs where the name is the variable name and the value is the variable value for service configuration.

Example

curl -s http://localhost:8510/node/userinput | jq
[
  {
    "serviceOrgid": "userdev",
    "serviceUrl": "mytest1",
    "serviceArch": "amd64",
    "serviceVersionRange": "[0.0.1,INFINITY)",
    "inputs": [
      {
        "name": "var1",
        "value": "aString"
      },
      {
        "name": "var2",
        "value": 22.2
      }
    ]
  },
  {
    "serviceOrgid": "userdev",
    "serviceUrl": "mytest2",
    "serviceArch": "amd64",
    "serviceVersionRange": "[2.0.1,INFINITY)",
    "inputs": [
      {
        "name": "city_name",
        "value": "New York"
      }
    ]
  }
]

API: POST /node/userinput

Set the node’s user input for the service configuration. The node on the exchange will be updated too with the new user input.

Parameters

body:

The body is an array of the following:

name	type	description
serviceOrgid	string	the organization of the service.
serviceUrl	string	the url of the service.
serviceArch	string	the architecture of the service.
serviceVersionRange	string	the version range of the service that the configuration applies to. The serviceVersionRange is in OSGI version format. The default is [0.0.0,INFINITY).
inputs	json	an array of name and value pairs where the name is the variable name and the value is the variable value for service configuration.

Response

code:

201 – success

Example

curl -s -w "%{http_code}" -X POST -H 'Content-Type: application/json'  -d '[
  {
    "serviceOrgid": "userdev",
    "serviceUrl": "mytest",
    "serviceArch": "amd64",
    "serviceVersionRange": "[0.0.1,INFINITY)",
    "inputs": [
      {
        "name": "city_name",
        "value": "New York"
      }
    ]
  }
]'  http://localhost:8510/node/userinput | jq '.'

API: PATCH /node/userinput

Patch the node’s user input for the service configuration. The node on the exchange will be updated too with the new user input.

Parameters

body:

The body is an array of the following:

name	type	description
serviceOrgid	string	the organization of the service.
serviceUrl	string	the url of the service.
serviceArch	string	the architecture of the service.
serviceVersionRange	string	the version range of the service that the configuration applies to. The serviceVersionRange is in OSGI version format. The default is [0.0.0,INFINITY).
inputs	json	an array of name and value pairs where the name is the variable name and the value is the variable value for service configuration.

Response

code:

201 – success

Example

curl -s -w "%{http_code}" -X PATCH -H 'Content-Type: application/json'  -d '[
  {
    "serviceOrgid": "userdev",
    "serviceUrl": "mytest2",
    "serviceArch": "amd64",
    "serviceVersionRange": "[2.0.1,INFINITY)",
    "inputs": [
      {
        "name": "my_var",
        "value": "aString"
      }
    ]
  }
]'  http://localhost:8510/node/userinput | jq '.'

API: DELETE /node/usrinput

Delete the node’s user input for service configuration. The exchange copy of the node’s user input will also be deleted.

Parameters

none

Response

code:

204 – success

body:

none

Example

curl -s -w "%{http_code}" -X DELETE "http://localhost:8510/node/userinput" | jq '.'
204

9. Node Policy

API: GET /node/policy

Get the node policy. The local node policy is alway in sync with the node policy on the exchange.

Parameters

none

Response

code:

200 – success

body:

name	type	description
properties	array	an array of the name-value pairs to describe the policy properties.
constraints	string	an array of constraint expressions of the form <property name> <operator> <property value>, separated by boolean operators AND (&&) or OR (\|\|).

Example

curl -s http://localhost:8510/node/policy | jq '.'
{
  "properties": [
    {
      "name": "purpose",
      "value": "network-testing"
    },
    {
      "name": "group",
      "value": "bluenode"
    },
    {
      "name": "openhorizon.cpu",
      "value": 2
    },
    {
      "name": "openhorizon.arch",
      "value": "amd64"
    },
    {
      "name": "openhorizon.memory",
      "value": 3946
    },
    {
      "name": "openhorizon.hardwareId",
      "value": "abcdefg"
    },
    {
      "name": "openhorizon.allowPrivileged",
      "value": false
    }
  ],
  "constraints": [
    "iame2edev == true"
    "prop1 == value && prop2 == 2"
  ]
}

API: POST /node/policy

Set the node policy. The node on the exchange will be updated too with the new policy. Properties openhorizon.cpu, openhorizon.arch, openhorizon.memory, openhorizon.hardwareId are buit-in properties which cannot be changed. When openhorizon.allowPrivileged is set to true the service container is allowed to run in the ‘privileged’ mode if it chooses to. The default value for openhorizon.allowPrivileged is false.

Parameters

body:

The body is an array of the following:

name	type	description
properties	array	an array of the name-value pairs to describe the policy properties.
constraints	string	an array of constraint expressions of the form <property name> <operator> <property value>, separated by boolean operators AND (&&) or OR (\|\|).

Response

code:

201 – success

Example

curl -s -w "%{http_code}" -X POST -H 'Content-Type: application/json'  -d '{
  "properties": [
    {
      "name": "purpose",
      "value": "network-testing"
    },
    {
      "name": "group",
      "value": "bluenode"
    }
  ],
  "constraints": [
    "iame2edev == true",
    "MyVar==2"
  ]
}'  http://localhost:8510/node/policy  | jq '.'

API: PATCH /node/policy

Patch the properties or the constraints for the node policy. The node on the exchange will be updated too with the new patch. Properties openhorizon.cpu, openhorizon.arch, openhorizon.memory, penhorizon.hardwareId are buit-in properties which cannot be changed. When openhorizon.allowPrivileged is set to true the service container is allowed to run in the ‘privileged’ mode if it chooses to. The default value for openhorizon.allowPrivileged is false.

Parameters

body:

The body is an array of the following:

name	type	description
properties	array	an array of the name-value pairs to describe the policy properties.
constraints	string	an array of constraint expressions of the form <property name> <operator> <property value>, separated by boolean operators AND (&&) or OR (\|\|).

Response

code:

201 – success

Example

curl -s -w "%{http_code}" -X PATCH -H 'Content-Type: application/json'  -d '{
  "constraints": [
    "iame2edev == false",
    "MyVar==3"
  ]
}'  http://localhost:8510/node/policy | jq '.'

API: DELETE /node/policy

Delete the node policy. The exchange copy of the node policy will also be deleted.

Parameters

none

Response

code:

204 – success

body:

none

Example

curl -s -w "%{http_code}" -X DELETE "http://localhost:8510/node/policy" | jq '.'
204

10. Node Management

API: GET /nodemanagement/nextjob

Get the status object of the next scheduled node management job. A node management job has a status object once its node management policy is picked up by the node management worker and matched to a node. If there are multiple NMP’s running on the node, the earliest scheduled NMP is returned. A guide to what each status value means can be found here: node_management_status.md

Parameters

name	type	description
type	string	the type of job to query. Currently, the only type of job is “agentUpgrade” for agent auto upgrade jobs. If this filter is omitted, all statuses will be queried regardless of type.
ready	boolean	if true, only statuses that are in the “downloaded” state (upgrade packages have been downloaded to the node) will be queried. If false, only statuses that are in the “waiting” state (upgrade packages have not been downloaded to the node) will be queried. If this filter is omitted, all statuses will be queried regardless of state.

Response

code:

200 – success

body:

agentUpgradePolicyStatus:

The following fields describe the status of an agent auto upgrade job as defined by the NMP created by a user. This is the structure that stays synchronized with the Exchange during the upgrade process.

name	subfield	type	description
scheduledTime		string	a RFC3339 timestamp designating when the upgrade job should start.
startTime		string	a RFC3339 timestamp designating when the upgrade job actually started. This field is populated when the agent auto upgrade cronjob picks up this job and changes the status to “initiated”.
endTime		string	a RFC3339 timestamp designating when the upgrade job completed successfully. This field is populated when the agent auto upgrade cronjob changes the status to “successful”.
upgradedVersions		json	a json structure that defines the versions being upgraded/downgraded to.
	softwareVersion	string	the version that the agent software packages are to be upgraded/downgraded to.
	certVersion	string	the version of the certificate file to be upgraded/downgraded to.
	configVersion	string	the version of the configuration file to be upgraded/downgraded to.
status		string	a string message that lists the current state of the upgrade job.
errorMessage		string	a string message containing any possible error messages that occur during the job.
workingDirectory		string	the directory that the upgrade job will be reading and writing files to.

agentUpgradeInternal:

The following fields describe the internal status object of an agent auto upgrade job used by the node management worker. This structure is an extension of the agentUpgradePolicyStatus structure that provides extra information to the node management worker needed to perform the upgrade.

name	subfield	type	description
allowDowngrade		boolean	a Boolean value that designates if a downgrade to a previous version is allowed to occur.
manifest		string	a string value that corresponds to an upgrade manifest in the Exchange.
scheduledUnixTime		string	a RFC3339 timestamp designating when the upgrade job should start in the local unix time.
latestMap		json	a json map that describes which upgrade types are to track and stay up-to-date with the latest available version.
	softwareLatest	boolean	a Boolean value that designates if the agent software packages should stay up-to-date with the latest available version.
	configLatest	boolean	a Boolean value that designates if the configuration file should stay up-to-date with the latest available version.
	certLatest	boolean	a Boolean value that designates if the certificate should stay up-to-date with the latest available version.

Example

curl -s http://localhost:8510/nodemanagement/nextjob?type=agentUpgrade&ready=true | jq '.'
{
  "e2edev/sample-nmp": {
    "agentUpgradePolicyStatus": {
      "scheduledTime": "2022-05-24T12:00:00Z",
      "startTime": "2022-05-24T12:00:01-07:00",
      "endTime": "2022-05-24T12:00:02-07:00",
      "upgradedVersions": {
        "softwareVersion": "2.30.0",
        "certVersion": "",
        "configVersion": ""
      },
      "status": "successful",
      "workingDirectory": "/var/horizon/nmp"
    },
    "agentUpgradeInternal": {
      "allowDowngrade": false,
      "manifest": "sample_manifest",
      "scheduledUnixTime": "2022-05-24T12:00:00-07:00",
      "latestMap": {
        "softwareLatest": true,
        "configLatest": false,
        "certLatest": false
      }
    }
  }
}

API: GET /nodemanagement/status

Get a map of all status objects that apply to the node. Each status object corresponds to a node management policy that has been matched to the node and picked up by the node management worker. A guide to what each status value means can be found here: node_management_status.md

Parameters

none

Response

code:

200 – success

body:

agentUpgradePolicyStatus:

The following fields describe the status of an agent auto upgrade job as defined by the NMP created by a user. This is the structure that stays synchronized with the Exchange during the upgrade process.

name	subfield	type	description
scheduledTime		string	a RFC3339 timestamp designating when the upgrade job should start.
startTime		string	a RFC3339 timestamp designating when the upgrade job actually started. This field is populated when the agent auto upgrade cronjob picks up this job and changes the status to “initiated”.
endTime		string	a RFC3339 timestamp designating when the upgrade job completed successfully. This field is populated when the agent auto upgrade cronjob changes the status to “successful”.
upgradedVersions		json	a json structure that defines the versions being upgraded/downgraded to.
	softwareVersion	string	the version that the agent software packages are to be upgraded/downgraded to.
	certVersion	string	the version of the certificate file to be upgraded/downgraded to.
	configVersion	string	the version of the configuration file to be upgraded/downgraded to.
status		string	a string message that lists the current state of the upgrade job.
errorMessage		string	a string message containing any possible error messages that occur during the job.
workingDirectory		string	the directory that the upgrade job will be reading and writing files to.

agentUpgradeInternal:

The following fields describe the internal status object of an agent auto upgrade job used by the node management worker. This structure is an extension of the agentUpgradePolicyStatus structure that provides extra information to the node management worker needed to perform the upgrade.

name	subfield	type	description
allowDowngrade		boolean	a Boolean value that designates if a downgrade to a previous version is allowed to occur.
manifest		string	a string value that corresponds to an upgrade manifest in the Exchange.
scheduledUnixTime		string	a RFC3339 timestamp designating when the upgrade job should start in the local unix time.
latestMap		json	a json map that describes which upgrade types are to track and stay up-to-date with the latest available version.
	softwareLatest	boolean	a Boolean value that designates if the agent software packages should stay up-to-date with the latest available version.
	configLatest	boolean	a Boolean value that designates if the configuration file should stay up-to-date with the latest available version.
	certLatest	boolean	a Boolean value that designates if the certificate should stay up-to-date with the latest available version.

Example

curl -s http://localhost:8510/nodemanagement/status | jq '.'
{
  "e2edev/sample-nmp": {
    "agentUpgradePolicyStatus": {
      "scheduledTime": "2022-05-24T11:00:00Z",
      "startTime": "2022-05-24T11:00:01-07:00",
      "endTime": "2022-05-24T11:00:02-07:00",
      "upgradedVersions": {
        "softwareVersion": "2.30.0",
        "certVersion": "1.0.0",
        "configVersion": "1.0.0"
      },
      "status": "successful",
      "workingDirectory": "/var/horizon/nmp"
    },
    "agentUpgradeInternal": {
      "allowDowngrade": true,
      "manifest": "sample_manifest",
      "scheduledUnixTime": "2022-05-24T11:00:00-07:00",
      "latestMap": {
        "softwareLatest": true,
        "configLatest": false,
        "certLatest": false
      }
    }
  },
  "e2edev/sample-nmp-2": {
    "agentUpgradePolicyStatus": {
      "scheduledTime": "2022-05-24T12:00:00Z",
      "startTime": "2022-05-24T12:00:01-07:00",
      "upgradedVersions": {
        "softwareVersion": "2.30.0",
        "certVersion": "1.0.0",
        "configVersion": "1.0.0"
      },
      "status": "failed",
      "errorMessage": "sample error message",
      "workingDirectory": "/var/horizon/nmp"
    },
    "agentUpgradeInternal": {
      "allowDowngrade": false,
      "manifest": "sample_manifest_2",
      "scheduledUnixTime": "2022-05-24T12:00:00-07:00",
      "latestMap": {
        "softwareLatest": true,
        "configLatest": true,
        "certLatest": true
      }
    }
  }
}

API: GET /nodemanagement/status/{nmpName}

Get the status objects that corresponds to the given node management policy name. The org that the NMP and node belong to can be optionally prepended (i.e. /nodemanagement/status/nmp-name and /nodemanagement/status/org/nmp-name refer to the same object, so long as the node is part of the given org) A guide to what each status value means can be found here: node_management_status.md

Parameters

none

Response

code:

200 – success

body:

agentUpgradePolicyStatus:

The following fields describe the status of an agent auto upgrade job as defined by the NMP created by a user. This is the structure that stays synchronized with the Exchange during the upgrade process.

name	subfield	type	description
scheduledTime		string	a RFC3339 timestamp designating when the upgrade job should start.
startTime		string	a RFC3339 timestamp designating when the upgrade job actually started. This field is populated when the agent auto upgrade cronjob picks up this job and changes the status to “initiated”.
endTime		string	a RFC3339 timestamp designating when the upgrade job completed successfully. This field is populated when the agent auto upgrade cronjob changes the status to “successful”.
upgradedVersions		json	a json structure that defines the versions being upgraded/downgraded to.
	softwareVersion	string	the version that the agent software packages are to be upgraded/downgraded to.
	certVersion	string	the version of the certificate file to be upgraded/downgraded to.
	configVersion	string	the version of the configuration file to be upgraded/downgraded to.
status		string	a string message that lists the current state of the upgrade job.
errorMessage		string	a string message containing any possible error messages that occur during the job.
workingDirectory		string	the directory that the upgrade job will be reading and writing files to.

agentUpgradeInternal:

The following fields describe the internal status object of an agent auto upgrade job used by the node management worker. This structure is an extension of the agentUpgradePolicyStatus structure that provides extra information to the node management worker needed to perform the upgrade.

name	subfield	type	description
allowDowngrade		boolean	a Boolean value that designates if a downgrade to a previous version is allowed to occur.
manifest		string	a string value that corresponds to an upgrade manifest in the Exchange.
scheduledUnixTime		string	a RFC3339 timestamp designating when the upgrade job should start in the local unix time.
latestMap		json	a json map that describes which upgrade types are to track and stay up-to-date with the latest available version.
	softwareLatest	boolean	a Boolean value that designates if the agent software packages should stay up-to-date with the latest available version.
	configLatest	boolean	a Boolean value that designates if the configuration file should stay up-to-date with the latest available version.
	certLatest	boolean	a Boolean value that designates if the certificate should stay up-to-date with the latest available version.

Example

curl -s http://localhost:8510/nodemanagement/status/sample-nmp | jq '.'
{
  "e2edev/sample-nmp": {
    "agentUpgradePolicyStatus": {
      "scheduledTime": "2022-05-24T11:00:00Z",
      "startTime": "2022-05-24T11:00:01-07:00",
      "endTime": "2022-05-24T11:00:02-07:00",
      "upgradedVersions": {
        "softwareVersion": "2.30.0",
        "certVersion": "1.0.0",
        "configVersion": "1.0.0"
      },
      "status": "successful",
      "workingDirectory": "/var/horizon/nmp"
    },
    "agentUpgradeInternal": {
      "allowDowngrade": true,
      "manifest": "sample_manifest",
      "scheduledUnixTime": "2022-05-24T11:00:00-07:00",
      "latestMap": {
        "softwareLatest": true,
        "configLatest": false,
        "certLatest": false
      }
    }
  }
}

API: PUT /nodemanagement/status/{nmpName}

Update the status object that corresponds to the given node management policy name. The org that the NMP and node belong to can be optionally prepended (i.e. /nodemanagement/status/nmp-name and /nodemanagement/status/org/nmp-name refer to the same object, so long as the node is part of the given org) A guide to what each status value means can be found here: node_management_status.md

Currently, the only supported update to the status object is the agentUpgradePolicyStatus structure.

Parameters

body:

agentUpgradePolicyStatus:

The following fields describe the status of an agent auto upgrade job as defined by the NMP created by a user. This is the structure that stays synchronized with the Exchange during the upgrade process.

name	type	description
startTime	string	a RFC3339 timestamp designating when the upgrade job actually started. This field can only be set if it has not been previously set and the status field is also changed to “initiated”.
endTime	string	a RFC3339 timestamp designating when the upgrade job actually started. This field can only be updated if it has not been previously set and the status field is also changed to “successful”.
status	string	a string message that lists the current state of the upgrade job.
errorMessage	string	a string message containing any possible error messages that occur during the job. This field can only be updated if the status field is also changed.

Response

code:

201 – success

Example

curl -s -w "%{http_code}" -X PUT -H 'Content-Type: application/json' -d '{
  "agentUpgradePolicyStatus": {
    "startTime": "2022-05-24T12:00:01-07:00",
    "status": "initiated"
  }
}'  http://localhost:8510/nodemanagement/status/sample-nmp

curl -s -w "%{http_code}" -X PUT -H 'Content-Type: application/json' -d '{
  "agentUpgradePolicyStatus": {
    "endTime": "2022-05-24T12:00:02-07:00",
    "status": "successful"
  }
}'  http://localhost:8510/nodemanagement/status/sample-nmp

curl -s -w "%{http_code}" -X PUT -H 'Content-Type: application/json' -d '{
  "agentUpgradePolicyStatus": {
    "status": "failed",
    "errorMessage": "Sample error message",
  }
}'  http://localhost:8510/nodemanagement/status/sample-nmp

API: PUT /nodemanagement/reset

Reset all of the NMP status objects that are stored on the node to the “waiting” state.

Response

code:

201 – success

Example

curl -s -w "%{http_code}" -X PUT -H 'Content-Type: application/json' http://localhost:8510/nodemanagement/reset

API: PUT /nodemanagement/reset/{nmpName}

Reset all of the NMP status objects that are stored on the node to the “waiting” state.

Reset the status object that corresponds to the given node management policy name to the “waiting” state. The org that the NMP and node belong to can be optionally prepended (i.e. /nodemanagement/status/nmp-name and /nodemanagement/status/org/nmp-name refer to the same object, so long as the node is part of the given org)

Response

code:

201 – success

Example

curl -s -w "%{http_code}" -X PUT -H 'Content-Type: application/json' http://localhost:8510/nodemanagement/reset/sample-nmp