JSON::RPC::Common(3) User Contributed Perl Documentation JSON::RPC::Common(3)NAMEJSON::RPC::Common - Transport agnostic JSON RPC helper objects
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
· 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.
· JSON::RPC::Common::Errors, a class that will provide dictionaries
of error codes for JSON-RPC 1.1 and 1.1-alt/2.0.
· 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
<http://groups.google.com/group/json-rpc/web/simple-method-
description-for-json-rpc-example> for an example
· Moose class to SMD translator
· 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.
· 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 <http://json-
rpc.org/wiki/specification>
JSON-RPC 1.1 working draft
http://json-rpc.org/wd/JSON-RPC-1-1-WD-20060807.html <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
<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
<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
<http://groups.google.com/group/json-rpc/web/json-rpc-over-http>
On the CPAN
JSON, JSON::RPC, RPC::JSON, HTTP::Engine, CGI::JSONRPC
VERSION CONTROL
This module is maintained using Darcs. You can get the latest version
from <http://nothingmuch.woobling.org/code>, and use "darcs send" to
commit changes.
AUTHOR
Yuval Kogman <nothingmuch@woobling.org>
COPYRIGHT
Copyright (c) 2008 Yuval Kogman. All rights reserved
This program is free software; you can redistribute
it and/or modify it under the same terms as Perl itself.
perl v5.14.1 2009-08-06 JSON::RPC::Common(3)
