/ 
JSON-RPC-Dispatcher-0.0300
River stage one • 1 direct dependent • 1 total dependent
/ JSON::RPC::Dispatcher

NAME

JSON::RPC::Dispatcher - A JSON-RPC 2.0 server.

VERSION

version 0.0300

SYNOPSIS

# 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"}

DESCRIPTION

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-1-2-proposal.

Advanced Error Handling

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.

 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.

PREREQS

Moose JSON Plack Plack::Request Test::More Sub::Name

TODO

Once the JSON-RPC 2.0 spec is finalized, this module may need to change to support any last minute changes or additions.

SUPPORT

Repository

http://github.com/plainblack/JSON-RPC-Dispatcher

Bug Reports

http://rt.cpan.org/Public/Dist/Display.html?Name=JSON-RPC-Dispatcher

SEE ALSO

You may also want to check out these other modules, especially if you're looking for something that works with JSON-RPC 1.x.

Dispatchers

Other modules that compete directly with this module, though perhaps on other protocol versions.

JSON::RPC

An excellent and fully featured both client and server for JSON-RPC 1.1.

POE::Component::Server::JSONRPC

A JSON-RPC 1.0 server for POE. I couldn't get it to work, and it doesn't look like it's maintained.

Catalyst::Plugin::Server::JSONRPC

A JSON-RPC 1.1 dispatcher for Catalyst.

CGI-JSONRPC

A CGI/Apache based JSON-RPC 1.1 dispatcher. Looks to be abandoned in alpha state. Also includes Apache2::JSONRPC.

AnyEvent::JSONRPC::Lite

An AnyEvent JSON-RPC 1.x dispatcher.

Sledge::Plugin::JSONRPC

JSON-RPC 1.0 dispatcher for Sledge MVC framework.

Clients

Modules that you'd use to access various dispatchers.

JSON::RPC::Common

A JSON-RPC client for 1.0, 1.1, and 2.0. Haven't used it, but looks pretty feature complete.

RPC::JSON

A simple and good looking JSON::RPC 1.x client. I haven't tried it though.

AUTHOR

JT Smith <jt_at_plainblack_com>

LEGAL

JSON::RPC::Dispatcher is Copyright 2009 Plain Black Corporation (http://www.plainblack.com/) and is licensed under the same terms as Perl itself.