/ 
JSON-RPC-Dispatcher-0.0100
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.0100

SYNOPSIS

# app.psgi
use JSON::RPC::Dispatcher;

my $rpc = JSON::RPC::Dispatcher->new;

sub add_em {
   my $params = shift;
   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 RPC

You can also get access to the procedure's internal data structures to do more advanced things. You do this by using the register_advanced method as in this example.

 use JSON::RPC::Dispatcher;
 my $rpc = JSON::RPC::Dispatcher->new;

 sub guess {
    my $proc = shift;
    my $guess = $proc->params->[0];
    if ($guess == 10) {
	    return 'Correct!';
    }
    elsif ($guess > 10) {
	    $proc->error_code(986);
    	$proc->error_message('Too high.');
    }
    else {
	    $proc->error_code(987);
    	$proc->error_message('Too low.');
    }
    $proc->error_data($guess);
    return undef;
 }

 $rpc->register_advanced( 'guess', \&guess );

 $rpc->to_app;

In the above example the guess subroutine gets direct access to the JSON::RPC::Dispatcher::Procedure object. This happens by calling register_advanced rather than register. By doing this you can set custom error codes, which can be used by your client application to implement more advanced functionality. You could also use this to throw exceptions for parameter validation and many other uses.

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 Test::Deep

TODO

This module still needs some work.

  • It has no test suite, and that needs to be fixed up asap. Although, all of the examples in the eg folder have been tested and work.

  • It doesn't support "notifications".

  • It's not strict about the protocol version number, or request id right now. Not sure if that's good or bad.

  • 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.