view release on metacpan or  search on metacpan

README  view on Meta::CPAN

SYNOPSIS
        package MyApp;
        use Catalyst qw/Server Server::JSONRPC/;

        package MyApp::Controller::Example;
        use base 'Catalyst::Controller';

        sub echo : JSONRPC {                     # available as: example.echo
            my ( $self, $c, @args ) = @_;
            $c->stash->{jsonrpc} = join ', ', @args;
        }

        sub ping : JSONRPCPath('/ping') {        # available as: ping
            my ( $self, $c ) = @_;
            $c->stash->{jsonrpc} = 'Pong';
        }

        sub world : JSONRPCRegex(/hello/) {      # available as: *hello*
            my ($self, $c) = @_;
            $c->stash->{jsonrpc} = 'World';
        }

        sub echo : JSONRPCLocal {                # available as: example.echo
            my ( $self, $c, @args ) = @_;
            $c->stash->{jsonrpc} = join ', ', @args;
        }

        sub ping : JSONRPCGlobal {               # available as: ping
            my ( $self, $c ) = @_;
            $c->stash->{jsonrpc} = 'Pong';
        }

DESCRIPTION
    JSONRPC Plugin for Catalyst which we tried to make compatible with the
    way Catalyst works with URLS. Main features are:

    *   Split JSONRPC methodNames by STRING to find out Controller.

    *   Single entrypoint for JSONRPC calls, like http://host.tld/rpc

    *   DispatchTypes (attributes) which work much the same as Catalyst
        attrs

    *   JSONRPC Parameter handling transparent to Catalyst parameter
        handling

HOW IT WORKS
    The default behaviour will handle JSONRPC Requests sent to "/rpc" by
    creating an OBJECT containing JSONRPC specific parameters in
    "$c->req->jsonrpc".

    Directly after, it will find out the Path of the Action to dispatch to,
    by splitting methodName by ".":

      methodName: hello.world
      path      : /hello/world

    From this point, it will dispatch to '/hello/world' when it exists, like
    Catalyst Urls would do. What means: you will be able to set Regexes,
    Paths etc on subroutines to define the endpoint.

    We discuss these custom JSONRPC attributes below.

    When the request is dispatched, we will return $c->stash->{jsonrpc} to
    the jsonrpc client, or, when it is not available, it will return
    $c->stash to the client. There is also a way of defining $c->stash keys
    to be send back to the client.

ATTRIBUTES
    You can mark any method in your Catalyst application as being available
    remotely by using one of the following attributes, which can be added to
    any existing attributes, except Private. Remember that one of the
    mentioned attributes below are automatically also Privates...

    JSONRPC
        Make this method accessible via JSONRPC, the same way as Local does
        when using catalyst by URL.

        The following example will be accessible by method "hello.world":

          package Catalyst::Controller::Hello
          sub world : JSONRPC {}

    JSONRPCLocal
        Identical version of attribute "JSONRPC"

    JSONRPCGlobal
        Make this method accessible via JSONRPC, the same way as GLOBAL does
        when using catalyst by URL.

        The following example will be accessible by method "ping":

          package Catalyst::Controller::Hello
          sub ping : JSONRPCGlobal {}

    JSONRPCPath('/say/hello')
        Make this method accessible via JSONRPC, the same way as Path does
        when using catalyst by URL.

        The following example will be accessible by method "say.hello":

          package Catalyst::Controller::Hello
          sub hello : JSONRPCPath('/say/hello') {}

    JSONRPCRegex('foo')
        Make this method accessible via JSONRPC, the same way as Regex does
        when using catalyst by URL.

        The following example will be accessible by example methods:
        "a.foo.method" "wedoofoohere" "foo.getaround"

          package Catalyst::Controller::Hello
          sub hello : JSONRPCPath('foo') {}

ACCESSORS
    Once you've used the plugin, you'll have an $c->request->jsonrpc
    accessor which will return an "Catalyst::Plugin::Server::JSONRPC"
    object.

    You can query this object as follows: