JSON::RPC::Common(3pm)

1JSON::RPC::Common(3)  User Contributed Perl Documentation JSON::RPC::Common(3)
2
3
4

NAME

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

SYNOPSIS

9               # this is a simplistic example
10               # you probably want to use L<JSON::RPC::Common::Marshal::Text> instead for
11               # something like this.
12
13               use JSON::RPC::Common::Procedure::Call;
14
15               # deserialize whatever json text you have into json data:
16               my $req = from_json($request_body);
17
18               # inflate it and get a call object:
19               my $call = JSON::RPC::Common::Procedure::Call->inflate($req);
20
21               warn $call->version;
22
23               # this will create a result object of the correct class/version/etc
24               # "value" is the return result, regardless of version
25               my $res = $call->return_result("value");
26
27               # finally, convert back to json text:
28               print to_json($res->deflate);
29

DESCRIPTION

31       This module provides abstractions for JSON-RPC 1.0, 1.1 (both
32       variations) and 2.0 (formerly 1.2) Procedure Call and Procedure Return
33       objects (formerly known as request and result), along with error
34       objects. It also provides marshalling objects to convert the model
35       objects into JSON text and HTTP requests/responses.
36
37       This module does not concern itself with the transport layer at all, so
38       the JSON-RPC 1.1 and the alternative specification, which are very
39       different on that level are implemented with the same class.
40

RANT

42       While JSON-RPC 1.0 and JSON-RPC 2.0 are beautifully simple, the JSON-
43       RPC 1.1 working draft, is most definitely not. It is a convoluted
44       protocol, and also demands a lot more complexity from the responders on
45       the server side (server side introspection ("system.describe"), strange
46       things relating to positional vs. named params...).
47
48       Unfortunately it appears that JSON-RPC 1.1 is the most popular variant.
49
50       Since the client essentially chooses the version of the RPC to be used,
51       for public APIs I reccomend that all versions be supported, but be
52       aware that a 1.1-WD server "MUST" implement service description in
53       order to be in compliance.
54
55       Anyway, enough bitching. I suggest making your servers 1.0+2.0, and
56       your clients 2.0.
57

CLASSES

59       There are various classes provided by JSON::RPC::Common.
60
61       They are designed for high reusability. All the classes are transport
62       and representation agnostic except for JSON::RPC::Common::Marshal::Text
63       and JSON::RPC::Common::Marshal::HTTP which are completely optional.
64
65   JSON::RPC::Common::Procedure::Call
66       This class and its subclasses implement Procedure Calls (requests) for
67       JSON-RPC 1.0, 1.1WD, 1.1-alt and 2.0.
68
69   JSON::RPC::Common::Procedure::Return
70       This class and its subclasses implement Procedure Returns (results) for
71       JSON-RPC 1.0, 1.1WD, 1.1-alt and 2.0.
72
73   JSON::RPC::Common::Procedure::Return::Error
74       This class and its subclasses implement Procedure Return error objects
75       for JSON-RPC 1.0, 1.1WD, 1.1-alt and 2.0.
76
77   JSON::RPC::Common::Marshal::Text
78       A filter object that uses JSON to serialize procedure calls and returns
79       to JSON text, including JSON-RPC standard error handling for
80       deserialization failure.
81
82   JSON::RPC::Common::Marshal::HTTP
83       A subclass of JSON::RPC::Common::Marshal::Text with additional methods
84       for marshaling between HTTP::Requests and
85       JSON::RPC::Common::Procedure::Call and HTTP::Response and
86       JSON::RPC::Common::Procedure::Return.
87
88       Also knows how to handle JSON-RPC 1.1 "GET" encoded requests (for all
89       versions), providing RESTish call semantics.
90

TODO

92       ·   JSON::RPC::Common::Handler, a generic dispatch table based handler,
93           useful for when you don't want to just blindly call methods on
94           certain objects using "call" in JSON::RPC::Common::Procedure::Call.
95
96       ·   JSON::RPC::Common::Errors, a class that will provide dictionaries
97           of error codes for JSON-RPC 1.1 and 1.1-alt/2.0.
98
99       ·   An object model for JSON-RPC 1.1 service description.
100
101           SMD is required by most JSON-RPC 1.1 over HTTP clients.
102
103           Since this is generally static, for now you can write one manually,
104           see
105           http://groups.google.com/group/json-rpc/web/simple-method-description-for-json-rpc-example
106           <http://groups.google.com/group/json-rpc/web/simple-method-
107           description-for-json-rpc-example> for an example
108
109       ·   Moose class to SMD translator
110
111       ·   MooseX::Storage enabled objects can serialize themselves into JSON,
112           and should DWIM when used. JSON-RPC 1.0 class hints could be used
113           here too.
114
115       ·   Convert to Squirrel for smaller deps and faster load time. Need to
116           find a solution for roles and type constraints. Neither is relied
117           on heavily.
118

VERSION CONTROL

145       This module is maintained using Darcs. You can get the latest version
146       from <http://nothingmuch.woobling.org/code>, and use "darcs send" to
147       commit changes.
148

AUTHOR

150       Yuval Kogman <nothingmuch@woobling.org>
151

COPYRIGHT

153               Copyright (c) 2008 Yuval Kogman. All rights reserved
154               This program is free software; you can redistribute
155               it and/or modify it under the same terms as Perl itself.
156
157
158
159perl v5.12.0                      2009-08-06              JSON::RPC::Common(3)