GSP
Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages


Manual Reference Pages  -  JSON::RPC::COMMON (3)

.ds Aq ’

NAME

JSON::RPC::Common - Transport agnostic JSON RPC helper objects

CONTENTS

VERSION

version 0.11

SYNOPSIS



        # this is a simplistic example
        # you probably want to use L<JSON::RPC::Common::Marshal::Text> instead for
        # something like this.

        use JSON::RPC::Common::Procedure::Call;

        # deserialize whatever json text you have into json data:
        my $req = from_json($request_body);

        # inflate it and get a call object:
        my $call = JSON::RPC::Common::Procedure::Call->inflate($req);

        warn $call->version;

        # this will create a result object of the correct class/version/etc
        # "value" is the return result, regardless of version
        my $res = $call->return_result("value");

        # finally, convert back to json text:
        print to_json($res->deflate);



DESCRIPTION

This module provides abstractions for JSON-RPC 1.0, 1.1 (both variations) and 2.0 (formerly 1.2) Procedure Call and Procedure Return objects (formerly known as request and result), along with error objects. It also provides marshalling objects to convert the model objects into JSON text and HTTP requests/responses.

This module does not concern itself with the transport layer at all, so the JSON-RPC 1.1 and the alternative specification, which are very different on that level are implemented with the same class.

RANT

While JSON-RPC 1.0 and JSON-RPC 2.0 are beautifully simple, the JSON-RPC 1.1 working draft, is most definitely not. It is a convoluted protocol, and also demands a lot more complexity from the responders on the server side (server side introspection (system.describe), strange things relating to positional vs. named params...).

Unfortunately it appears that JSON-RPC 1.1 is the most popular variant.

Since the client essentially chooses the version of the RPC to be used, for public APIs I reccomend that all versions be supported, but be aware that a 1.1-WD server MUST implement service description in order to be in compliance.

Anyway, enough bitching. I suggest making your servers 1.0+2.0, and your clients 2.0.

CLASSES

There are various classes provided by JSON::RPC::Common.

They are designed for high reusability. All the classes are transport and representation agnostic except for JSON::RPC::Common::Marshal::Text and JSON::RPC::Common::Marshal::HTTP which are completely optional.

    JSON::RPC::Common::Procedure::Call

This class and its subclasses implement Procedure Calls (requests) for JSON-RPC 1.0, 1.1WD, 1.1-alt and 2.0.

    JSON::RPC::Common::Procedure::Return

This class and its subclasses implement Procedure Returns (results) for JSON-RPC 1.0, 1.1WD, 1.1-alt and 2.0.

    JSON::RPC::Common::Procedure::Return::Error

This class and its subclasses implement Procedure Return error objects for JSON-RPC 1.0, 1.1WD, 1.1-alt and 2.0.

    JSON::RPC::Common::Marshal::Text

A filter object that uses JSON to serialize procedure calls and returns to JSON text, including JSON-RPC standard error handling for deserialization failure.

    JSON::RPC::Common::Marshal::HTTP

A subclass of JSON::RPC::Common::Marshal::Text with additional methods for marshaling between HTTP::Requests and JSON::RPC::Common::Procedure::Call and HTTP::Response and JSON::RPC::Common::Procedure::Return.

Also knows how to handle JSON-RPC 1.1 GET encoded requests (for all versions), providing RESTish call semantics.

TODO

o JSON::RPC::Common::Handler, a generic dispatch table based handler, useful for when you don’t want to just blindly call methods on certain objects using call in JSON::RPC::Common::Procedure::Call.
o JSON::RPC::Common::Errors, a class that will provide dictionaries of error codes for JSON-RPC 1.1 and 1.1-alt/2.0.
o An object model for JSON-RPC 1.1 service description.

SMD is required by most JSON-RPC 1.1 over HTTP clients.

Since this is generally static, for now you can write one manually, see <http://groups.google.com/group/json-rpc/web/simple-method-description-for-json-rpc-example> for an example

o Moose class to SMD translator
o MooseX::Storage enabled objects can serialize themselves into JSON, and should DWIM when used. JSON-RPC 1.0 class hints could be used here too.
o Convert to Squirrel for smaller deps and faster load time. Need to find a solution for roles and type constraints. Neither is relied on heavily.

SEE ALSO

    On the Intertubes

JSON-RPC 1.0 specification <http://json-rpc.org/wiki/specification>
JSON-RPC 1.1 working draft <http://json-rpc.org/wd/JSON-RPC-1-1-WD-20060807.html>
JSON-RPC 1.1 alternative specification proposal <http://groups.google.com/group/json-rpc/web/json-rpc-1-1-alt>
JSON-RPC 2.0 specification proposal <http://groups.google.com/group/json-rpc/web/json-rpc-1-2-proposal>
Simplified encoding of JSON-RPC over HTTP <http://groups.google.com/group/json-rpc/web/json-rpc-over-http>

    On the CPAN

JSON, JSON::RPC, RPC::JSON, HTTP::Engine, CGI::JSONRPC

AUTHOR

Yuval Kogman <nothingmuch@woobling.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2014 by Yuval Kogman and others.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

Search for    or go to Top of page |  Section 3 |  Main Index


perl v5.20.3 JSON::RPC::COMMON (3) 2014-02-28

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.