NAME

Plack::App::JSON::RPC - A JSON-RPC 2.0 server.

VERSION

version 0.0100

SYNOPSIS

# app.psgi
use Plack::App::JSON::RPC;

my $rpc = Plack::App::JSON::RPC->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 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 Plack::App::JSON::RPC;
 my $rpc = Plack::App::JSON::RPC->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 Plack::App::JSON::RPC::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.

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/Plack-App-JSON-RPC

Bug Reports

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

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.

JSON::RPC

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

JSON::RPC::Common

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

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.

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

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

cpanm Plack::App::JSON::RPC

perl -MCPAN -e shell
install Plack::App::JSON::RPC