RPC

From ago control wiki
Jump to: navigation, search

Contents

JSON-RPC Interface

ago control provides a JSON-RPC interface. It is implemented in the agorpc daemon. It is written in C++ and uses the mongoose embedded web server to provide an HTTP(S) interface on ports 8008 and 8009 (SSL) by default. You can adjust these by specifying a ports option in the RPC config section:

[rpc]
ports=8008,8009s

The "s" is no typo, it specifies that this port is used for SSL.

All JSON-RPC calls are made towards the endpoint "/jsonrpc". The JSON parsing is done with jsoncpp. You can find more information regarding JSON-RPC here: Specification


A basic JSON-RPC request will always have these fields:

{"jsonrpc" : "2.0",
  "method" : "some-method",
  "params" : {....},
  "id":1
}

Methods

The following methods are implemented:

message

The message method will send an AMQP message to ago control with "content" as content. This example will switch off a specific uuid:

 {"jsonrpc" : "2.0", 
  "method" : "message", 
  "params" : {
    "content":{
      "command":"off",
      "uuid":"0962f27e-99ce-43a4-872b-97d75d61f464"
    }
  }, 
  "id":1
}

This call will fetch the inventory from the Resolver:

 {"jsonrpc" : "2.0", 
  "method" : "message", 
  "params" : {
    "content":{
      "command":"inventory"
    }
  }, 
  "id":1
}

The response format is described in MessageFormat


To send an event also add a "subject" parameter to "params".

subscribe

Subscriptions are used to listen to broadcasted events on the Agocontrol message bus.

This will create a subscription and provide a uuid for it. You can use the getevent call afterwards to fetch any events that did occur.

Request

{
    "method": "subscribe",
    "id": 1,
    "jsonrpc": "2.0"
}

Response

{
    "jsonrpc": "2.0",
    "result": "2d28cb85-5be0-4ccb-bc21-33bf94ed04ec",
    "id": 1
}


getevent

The getevent method will fetch an event from the queue. If no event is in the queue, this call will block until the next event occurs.

{
    "method": "getevent",
    "params": {
        "uuid": "2d28cb85-5be0-4ccb-bc21-33bf94ed04ec"
    },
    "id": 2,
    "jsonrpc": "2.0"
}

Response

{
    "jsonrpc": "2.0",
    "result": {
        "event": "event.environment.timechanged",
        "day": 2,
        "hour": 22,
        "minute": 10,
        "month": 1,
        "second": 0,
        "weekday": 3,
        "yday": 1,
        "year": 2013
    },
    "id": 2
}

unsubscribe

If you don't want to fetch events anymore you need to unsubscribe:

Request

{
    "method": "unsubscribe",
    "params": {
        "uuid": "2d28cb85-5be0-4ccb-bc21-33bf94ed04ec"
    },
    "id": 3,
    "jsonrpc": "2.0"
}


Examples

Javascript

Note: if developing in the Agocontrol Web UI, you never need to deal with lowlevel code like this. Instead use the sendCommand methods (TODO: Document)

var url = "/jsonrpc";

function displayEvent(response) {
	if (response.result) { 
		console.log(response.result)
	}
	getevent();
}

function getevent() {
	var request = {};
	request.method = "getevent";
	request.params = {};
	request.params.uuid = "2d28cb85-5be0-4ccb-bc21-33bf94ed04ec";
	request.id = 1;
	request.jsonrpc = "2.0";

	$.post(url, JSON.stringify(request), displayEvent, "json");

}
Personal tools