Json-rpc

JSON-RPC is a standardized method of remotely calling procedures, and how to handle their replies. JSON-RPC can be used over sockets, ZMQ, http, etc. It generally leverages the http requests/response system to exchange information.

Official Standard

http://www.jsonrpc.org/specification

Components

The JSON-RPC standard formalizes a way of running commands on a remote server. The socket or webserver is sent a JSON object with the following information:

Request Object

{
	"jsonrpc" : "2.0",                    // string with the version of json-rpc protocol we are using
	"method"  : "your_function",          // name of the function we are running remotely
	"params"  : {"argA": 1, "argB": 2} ,  // dictionary of keyword arguments to pass to your function
	            //OR
	            [1,2],                    // list of positional arguments
	"id"      : 0,                        // an integer, or a string used to uniquely link the request with a response.
}

Response Object

{
	"jsonrpc" : "2.0",                    // json-rpc protocol vesion
	"result"  : {...},                    // on SUCCESSFUL runs only, a dictionary
	"id"      : 0,                        // an integer or string used to uniquely link the request with a response
	
	// error only
	"error"   : {                         // an error object (ONLY ON UNSUCCESSFUL RUNS)
		"code"    : 1    ,                 // integer indicating error type
		"message" : "blah",                // single sentence summarizing error code
		"data"    : {...},                 // dictionary of anything you'd like.
	}
}

Special Exceptions

method names

methods names beginning with rpc are reserved for internal methods.

error codes

error codes between/including -32768 to -32000 are reserved for internal (json-rpc) errors