JSON::RPC::Dispatcher - A JSON-RPC 2.0 server.
version 0.0506
In app.psgi:
use JSON::RPC::Dispatcher; my $rpc = JSON::RPC::Dispatcher->new; sub add_em { my @params = @_; my $sum = 0; $sum += $_ for @params; return $sum; } $rpc->register( 'sum', \&add_em ); $rpc->to_app;
Then run it:
plackup app.psgi
Now you can then call this service via a GET like:
http://example.com/?method=sum;params=[2,3,5];id=1
Or by posting JSON to it like this:
{"jsonrpc":"2.0","method":"sum","params":[2,3,5],"id":"1"}
And you'd get back:
{"jsonrpc":"2.0","result":10,"id":"1"}
Using this app you can make any PSGI/Plack aware server a JSON-RPC 2.0 server. This will allow you to expose your custom functionality as a web service in a relatiely tiny amount of code, as you can see above.
This module follows the draft specficiation for JSON-RPC 2.0. More information can be found at http://groups.google.com/group/json-rpc/web/json-rpc-2-0.
The register method takes a third argument which is a hash reference of named options that effects how the code should be handled.
register
The first argument passed into the function will be a reference to the Plack::Request object, which is great for getting environment variables, and HTTP headers if you need those things in processing your RPC.
$rpc->register( 'some_func', \&some_func, { with_plack_request => 1 }); sub some_func { my ($plack_request, $other_arg) = @_; ... }
TIP: Before using this option consider whether you might be better served by a Plack::Middleware component. For example, if you want to do HTTP Basic Auth on your requests, use Plack::Middleware::Basic::Auth instead.
You can also throw error messages rather than just dieing, which will throw an internal server error. To throw a specific type of error, die, carp, or confess, an array reference starting with the error code, then the error message, and finally ending with error data (optional). When JSON::RPC::Dispatcher detects this, it will throw that specific error message rather than a standard internal server error.
die
carp
confess
use JSON::RPC::Dispatcher; my $rpc = JSON::RPC::Dispatcher->new; sub guess { my ($guess) = @_; if ($guess == 10) { return 'Correct!'; } elsif ($guess > 10) { die [986, 'Too high.']; } else { die [987, 'Too low.']; } } $rpc->register( 'guess', \&guess ); $rpc->to_app;
NOTE: If you don't care about setting error codes and just want to set an error message, you can simply die in your RPC and your die message will be inserted into the error_data method.
error_data
JSON::RPC::Dispatcher allows for logging via Log::Any. This way you can set up logs with Log::Dispatch, Log::Log4perl, or any other logging system that Log::Any supports now or in the future. It's relatively easy to set up. In your app.psgi simply add a block like this:
use Log::Any::Adapter; use Log::Log4perl; Log::Log4perl::init('/path/to/log4perl.conf'); Log::Any::Adapter->set('Log::Log4perl');
That's how easy it is to start logging. You'll of course still need to configure the log4perl.conf file, which goes well beyond the scope of this document. And you'll also need to install Log::Any::Adapter::Log4perl to use this example.
JSON::RPC::Dispatcher logs the following:
Requests and responses.
In the case when there is an unhandled exception, anything other than the error message will be put into a debug log entry.
If an exception is thrown that has a trace method, then it's contents will be put into a trace log entry.
trace
All errors that are gracefully handled by the system will be put into an error log entry.
All errors that are not gracefully handled by the system will be put into a fatal log entry. Most of the time this means there's something wrong with the request document itself.
Moose JSON Plack Test::More Log::Any
http://github.com/plainblack/JSON-RPC-Dispatcher
http://github.com/plainblack/JSON-RPC-Dispatcher/issues
You may also want to check out these other modules, especially if you're looking for something that works with JSON-RPC 1.x.
Other modules that compete directly with this module, though perhaps on other protocol versions.
An excellent and fully featured both client and server for JSON-RPC 1.1.
A JSON-RPC 1.0 server for POE. I couldn't get it to work, and it doesn't look like it's maintained.
A JSON-RPC 1.1 dispatcher for Catalyst.
A CGI/Apache based JSON-RPC 1.1 dispatcher. Looks to be abandoned in alpha state. Also includes Apache2::JSONRPC.
An AnyEvent JSON-RPC 1.x dispatcher.
JSON-RPC 1.0 dispatcher for Sledge MVC framework.
Modules that you'd use to access various dispatchers.
A JSON-RPC client for 1.0, 1.1, and 2.0. Haven't used it, but looks pretty feature complete.
A simple and good looking JSON::RPC 1.x client. I haven't tried it though.
JT Smith <jt_at_plainblack_com>
JSON::RPC::Dispatcher is Copyright 2009-2010 Plain Black Corporation (http://www.plainblack.com/) and is licensed under the same terms as Perl itself.
To install JSON::RPC::Dispatcher, copy and paste the appropriate command in to your terminal.
cpanm
cpanm JSON::RPC::Dispatcher
CPAN shell
perl -MCPAN -e shell install JSON::RPC::Dispatcher
For more information on module installation, please visit the detailed CPAN module installation guide.