NAME
JRPC::Client - JSON-RPC 2.0 Client
SYNOPSIS
use JRPC::Client;
my $client = JRPC::Client->new();
$req = $client->new_request("http://jservices.com/WorldTime");
my $resp = $req->call('Timeinfo.getlocaltime', {'tzname' => 'CET', 'clockhrs' => '24'});
if (my $err = $resp->error()) { die("$err->{'message'}"); }
my $res = $resp->result();
print("Local time in CET is: $res->{'timeiso'}\n");DESCRIPTION
JRPC::Client is a Perl LWP based JSON-RPC 2.0 Client hoping to minimize tedious boilerplate code for JSON-RPC interaction, yet enabling advanced use cases by the power of LWP / HTTP::Request.
JRPC::Client complies to conventions of JSON-RPC 2.0, but it can be coerced to be used for other versions as well.
$client = JRPC::Client->new()
Instantiate a new JSON-RPC (2.0) Client. HTTP keep-alive is turned on, cookie store is established and default user-agent name is set here. Any of the LWP::UserAgent methods are callable on the returned object as JRPC::Client IS-A LWP::UserAgent.
The lifetime of the JRPC::Client can be kept long (e.g. throughout app) and it can usually be kept as single instance in app runtime (singleton, however JRPC::Client does not control singularity of instantiation). The factory method method new_request() takes care of instatiating requests for various URL:s, various methods.
$req = $client->new_request($url, %opts)
Factory method to instantiate and prepare a new JSON-RPC request to a URL. Options in %opts:
'mime' - Mime content-type for request (default: 'application/json')
'debug' - Dump Request after instantiation (to STDERR).
$resp = $req->call($method, $params, %opts)
Call a method previously prepared as a HTTP::Request on a URL (see new_request()). The JSON-RPC parameters passed as $param may be either a perl data structure (reference) or a filename (string).
Valid JSON string
a Perl runtime data-structure with JSON serializable elements.
In either case above (as a bit of forgiving behaviour) also passing a complete JSON-RPC message is allowed for covenience. A complete JSON-RPC message is detected by the presence of members 'id', 'jsonrpc', 'params' and 'method', which (especially all at the same time, together) are extremely unlikely to appear in the parameters. In the case of passing a complete message, the method found in message overrides the $meth passed params.
Optional KW parameters in %opts:
notify - Treat call as JSON-RPC notification. Ignore response (do not parse it).
debug - Produce debug output for call() phase
Note: on regular call (i.e. non-notification by 'notify' => 0) call() method parses the JSON response and expects it to be valid JSON, but it does not validate the JSON-RPC envelope (for presence of mandatory members).
Return (LWP) HTTP response object.
Further access by $resp->result() will evaluate the validity of the envelope.
RESPONSE METHODS
These methods magically appear in the HTTP::Response for the purposes of JRPC::Client::Request.
$resp->result()
JSON_RPC response "result" (as native data structure)
$resp->error()
JSON_RPC response "error" (as native data structure)
INTERNAL METHODS
These methods should not be of interest to a user of the productivity API (as demonstrated in SYNOPSIS).
is_message($msg)
Internal check to see if the passed structure looks like a JSON-RPC message envelope. To do so, the handle must be a ref to a hash and contain envelope parameters 'id', 'jsonrpc', 'params' and 'method'. is_message() is used to differentiate between complete messages and parameters-only to provide a forgiving behaviour on higher level functions (see call() method)
envelope($meth, $params, %opts)
Internal method to generate message envelope for method $meth and parameters passed. The $params should be checked by is_message() first to have the correct (non double wrapped) envelope created here.
Method in $meth must be passed to generate message envelope.