NAME

MojoX::JSONRPC2::HTTP - Client for JSON RPC 2.0 over HTTP

SYNOPSIS

    use MojoX::JSONRPC2::HTTP;

    $client = MojoX::JSONRPC2::HTTP->new;

    # setup
    $client
        ->url('http://example.com/endpoint')
        ->method('GET')
        ->type('application/json-rpc')
        ->headers({'X-Answer'=>42,…})
        ;
    # get Mojo::UserAgent to setup it (timeouts, etc.)
    $ua = $client->ua;

    # blocking notifications and calls
    ($failed, $result, $error) = $client->call('method', @params);
    ($failed, $result, $error) = $client->call_named('method', %params);
    $failed = $client->notify('method', @params);
    $failed = $client->notify_named('method', %params);

    # non-blocking calls
    $client->call('method', @params, \&cb);
    $client->call_named('method', %params, \&cb);
    sub cb {
        my ($failed, $result, $error) = @_;
    }

    # non-blocking notifications
    $client->notify('method', @params, \&cb_failed);
    $client->notify_named('method', %params, \&cb_failed);
    sub cb_failed {
        my ($failed) = @_;
    }

DESCRIPTION

Provide HTTP transport for JSON RPC 2.0 using Mojo::UserAgent.

Implements this spec: http://www.simple-is-better.org/json-rpc/transport_http.html. The "pipelined Requests/Responses" is not supported yet.

ATTRIBUTES

All these methods return current value when called without params or set new value and return their object (to allow method chaining) when called with single param.

url

RPC endpoint url.

This is only required parameter which must be set before doing RPC calls.

method

Default is 'POST', and only another supported value is 'GET'.

type

Default is 'application/json'.

headers

Default is empty HASHREF. Either modify it by reference or set it to your own HASHREF with any extra headers you need to send with RPC call.

ua

Mojo::UserAgent object used for sending HTTP requests - feel free to setup it or replace with your own object.

METHODS

new( %attrs )

new( \%attrs )

You can set attributes listed above by providing their values when calling new() or later using individual attribute methods.

call( 'method', @params )

call( 'method', @params, \&cb )

call_named( 'method', %params )

call_named( 'method', %params, \&cb )

Do blocking or non-blocking (when \&cb param provided) RPC calls, with either positional or named params. Blocking calls will return these values (non-blocking will call \&cb with same values as params):

    ($failed, $result, $error)

In case of transport-level errors, when we fail to either send RPC request or receive correct reply from RPC server the $failed will contain error message, while $result and $error will be undefined.

In case remote 'method' or RPC server itself will return error it will be available in $error as HASHREF with keys {code}, {message} and optionally {data}, while $failed and $result will be undefined.

Otherwise value returned by remote 'method' will be in $result, while $failed and $error will be undefined.

notify( 'method', @params )

notify( 'method', @params, \&cb )

notify_named( 'method', %params )

notify_named( 'method', %params, \&cb )

Do blocking or non-blocking (when \&cb param provided) RPC calls, with either positional or named params. Blocking calls will return this value (non-blocking will call \&cb with same value as param):

    $failed

It will contain error message in case of transport-level error or will be undefined if RPC call was executes successfully.

SEE ALSO

JSON::RPC2::Client, Mojolicious, Mojolicious::Plugin::JSONRPC2.

BUGS AND LIMITATIONS

Batch/Multicall feature

Not supported because it is not implemented by JSON::RPC2::Client.

No bugs have been reported.

SUPPORT

Please report any bugs or feature requests through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=MojoX-JSONRPC2-HTTP. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

You can also look for information at:

• RT: CPAN's request tracker

  http://rt.cpan.org/NoAuth/Bugs.html?Dist=MojoX-JSONRPC2-HTTP

• AnnoCPAN: Annotated CPAN documentation

  http://annocpan.org/dist/MojoX-JSONRPC2-HTTP

• CPAN Ratings

  http://cpanratings.perl.org/d/MojoX-JSONRPC2-HTTP

• Search CPAN

  http://search.cpan.org/dist/MojoX-JSONRPC2-HTTP/

AUTHOR

Alex Efros <powerman@cpan.org>

LICENSE AND COPYRIGHT

Copyright 2014 Alex Efros <powerman@cpan.org>.

This program is distributed under the MIT (X11) License: http://www.opensource.org/licenses/mit-license.php

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.