VOLTTRON Central Web Services Api Documentation¶
VOLTTRON Central (VC) is meant to be the hub of communication within a cluster of VOLTTRON instances. VC exposes a JSON-RPC 2.0 based API that allows a user to control multiple instances of VOLTTRON.
Why JSON-RPC¶
SOAP messaging is unfriendly to many developers, especially those wanting to make calls in a browser from AJAX environment. We have therefore have implemented a JSON-RPC API capability to VC, as a more JSON/JavaScript friendly mechanism.
How the API is Implemented¶
All calls are made through a POST to /vc/jsonrpc
All calls (not including the call to authenticate) will include an authorization token (a json-rpc extension).
JSON-RPC Request Payload¶
All posted JSON payloads will look like the following block:
{
"jsonrpc": "2.0",
"method": "method_to_invoke",
"params": {
"param1name": "param1value",
"param2name": "param2value"
},
"id": "unique_message_id",
"authorization": "server_authorization_token"
}
As an alternative, the params can be an array as illustrated by the following:
{
"jsonrpc": "2.0",
"method": "method_to_invoke",
"params": [
"param1value",
"param2value"
],
"id": "unique_message_id",
"authorization": "server_authorization_token"
}
For full documentation of the Request object please see section 4 of the JSON-RPC 2.0 specification.
JSON-RPC Response Payload¶
All responses shall have either an either an error response or a result response. The result key shown below can be a single instance of a JSON type, an array or a JSON object.
A result response will have the following format:
{
"jsonrpc": "2.0",
"result": "method_results",
"id": "sent_in_unique_message_id"
}
An error response will have the following format:
{
"jsonrpc": "2.0",
"error": {
"code": "standard_code_or_extended_code",
"message": "error message"
}
"id": "sent_in_unique_message_id_or_null"
}
For full documentation of the Response object please see section 5 of the JSON-RPC 2.0 specification.
JSON-RPC Data Objects¶
Key |
Type |
Value |
---|---|---|
uuid |
string |
A unique identifier for the platform. |
name |
string |
A user defined string for the platform. |
status |
Status |
A status object for the platform. |
Key |
Type |
Value |
---|---|---|
uuid |
string |
A unique identifier for the platform. |
name |
string |
A user defined string for the platform. |
status |
Status |
A status object for the platform. |
Key |
Type |
Value |
---|---|---|
uuid |
string |
A unique identifier for the agent. |
name |
string |
Defaults to the agentid of the installed agent |
tag |
string |
A shortcut that can be used for referencing the agent |
priority |
int |
If this is set the agent will autostart on the instance. |
process_id |
int |
The process id or null if not running. |
status |
string |
A status string made by the status rpc call, on an agent. |
Key |
Type |
Value |
---|---|---|
name |
||
discovery_address |
Key |
Type |
Value |
---|---|---|
name |
||
vip_address |
Key |
Type |
Value |
---|---|---|
uuid |
string |
A unique identifier for the platform. |
name |
string |
A user defined string for the platform. |
status |
Status |
A status object for the platform. |
Key |
Type |
Value |
---|---|---|
uuid |
string |
A unique identifier for the platform. |
name |
string |
A user defined string for the platform. |
status |
Status |
A status object for the platform. |
Key |
Type |
Value |
---|---|---|
uuid |
string |
A unique identifier for the platform. |
name |
string |
A user defined string for the platform. |
status |
Status |
A status object for the platform. |
Key |
Type |
Value |
---|---|---|
status |
string |
A value of GOOD, BAD, UNKNOWN, SUCCESS, FAIL |
context |
string |
Provides context about what the status means (optional) |
JSON-RPC API Methods¶
method |
parameters |
returns |
---|---|---|
get_authentication |
(username, password) |
authentication token |
Messages¶
- Retrieve Authorization Token
# POST /vc/jsonrpc { "jsonrpc": "2.0", "method": "get_authorization", "params": { "username": "dorothy", "password": "toto123" }, "id": "someID" }
- Response Success
# 200 OK { "jsonrpc": "2.0", "result": "someAuthorizationToken", "id": "someID" }
Failure
HTTP Status Code 401
- Register a VOLTTRON Platform Instance (Using Discovery)
# POST /vc/jsonrpc { "jsonrpc": "2.0", "method": "register_instance", "params": { "discovery_address": "http://127.0.0.2:8080", "display_name": "foo" # Optional } "authorization": "someAuthorizationToken", "id": "someID" }
- Success
# 200 OK { "jsonrpc": "2.0", "result": { "status": { "code": "SUCCESS" "context": "Registered instance foo" # or the uri if not specified. } }, "id": "someID" }
- Unregister a Volttron Platform Instance
# POST /vc/jsonrpc { "jsonrpc": "2.0", "method": "unregister_platform", "params": { "platform_uuid": "somePlatformUuid", } "authorization": "someAuthorizationToken", "id": "someID" }
- Retrieve Managed Instances
#POST /vc/jsonrpc { "jsonrpc": "2.0", "method": "list_platforms", "authorization": "someAuthorizationToken", "id": # }
- Response Success
200 OK { "jsonrpc": "2.0", "result": [ { "name": "platform1", "uuid": "abcd1234-ef56-ab78-cd90-efabcd123456", "health": { "status": "GOOD", "context": null, "last_updated": "2016-04-27T19:47:05.184997+00:00" } }, { "name": "platform2", "uuid": "0987fedc-65ba-43fe-21dc-098765bafedc", "health": { "status": "BAD", "context": "Expected 9 agents running, but only 5 are", "last_updated": "2016-04-27T19:47:05.184997+00:00", } }, { "name": "platform3", "uuid": "0000aaaa-1111-bbbb-2222-cccc3333dddd", "health": { "status": "GOOD", "context": "Currently scraping 20 devices", "last_updated": "2016-04-27T19:47:05.184997+00:00", } } ], "id": # }
- Retrieve Installed Agents From Platform
# POST /vc/jsonrpc { "jsonrpc": "2.0", "method": "platforms.uuid.abcd1234-ef56-ab78-cd90-efabcd123456.list_agents", "authorization": "someAuthorizationToken", "id": # }
- Response Success
200 OK { "jsonrpc": "2.0", "result": [ { "name": "HelloAgent", "identity": "helloagent-0.0_1", "uuid": "a1b2c3d4-e5f6-a7b8-c9d0-e1f2a3b4c5d6", "process_id": 3142, "error_code": null, "is_running": true, "permissions": { "can_start": true, "can_stop": true, "can_restart": true, "can_remove": true } "health": { "status": "GOOD", "context": null } }, { "name": "Historian", "identity": "sqlhistorianagent-3.5.0_1", "uuid": "a1b2c3d4-e5f6-a7b8-c9d0-e1f2a3b4c5d6", "process_id": 3143, "error_code": null, "is_running": true, "permissions": { "can_start": true, "can_stop": true, "can_restart": true, "can_remove": true } "health": { "status": "BAD", "context": "No publish in last 5 minutes" } }, { "name": "VolltronCentralPlatform", "identity": "platform.agent", "uuid": "a1b2c3d4-e5f6-a7b8-c9d0-e1f2a3b4c5d6", "process_id": 3144, "error_code": null, "is_running": true, "permissions": { "can_start": false, "can_stop": false, "can_restart": true, "can_remove": false } "health": { "status": "BAD", "context": "One agent has reported bad status" } }, { "name": "StoppedAgent-0.1", "identity": "stoppedagent-0.1_1", "uuid": "a1b2c3d4-e5f6-a7b8-c9d0-e1f2a3b4c5d6", "process_id": null, "error_code": 0, "is_running": false,s "health": { "status": "UNKNOWN", "context": "Error code -15" } "permissions": { "can_start": true, "can_stop": false, "can_restart": true, "can_remove": true } } ], "id": # }
- Install Agent
# POST /vc/jsonrpc { "jsonrpc": "2.0", "method": "platforms.uuid.0987fedc-65ba-43fe-21dc-098765bafedc.install", "params": { "files": [ { "file_name": "helloagent-0.1-py2-none-any.whl", "file": "data:application/octet-stream;base64,..." }, { "file_name": "some-non-wheel-file.txt", "file": "data:application/octet-stream;base64,..." }, ... ], } "authorization": "someAuthorizationToken", "id": # }
- Success Response
200 OK { "jsonrpc": "2.0", "result": { [ { "uuid": "a1b2c3d4-e5f6-a7b8-c9d0-e1f2a3b4c5d6" }, { "error": "Some error message" }, ... ] }, "id": # }
- Remove An Agent
# POST /vc/jsonrpc { "jsonrpc": "2.0", "method": "platforms.uuid.0987fedc-65ba-43fe-21dc-098765bafedc.remove_agent", "params": ["a1b2c3d4-e5f6-a7b8-c9d0-e1f2a3b4c5d6"], "authorization": "someAuthorizationToken", "id": # }
- Response Success
200 OK { "jsonrpc": "2.0", "result": { "process_id": 1000, "return_code": 0 }, "id": # }