1JSON::RPC::Common(3) User Contributed Perl Documentation JSON::RPC::Common(3)
2
3
4
6 JSON::RPC::Common - Transport agnostic JSON RPC helper objects
7
9 version 0.11
10
12 # this is a simplistic example
13 # you probably want to use L<JSON::RPC::Common::Marshal::Text> instead for
14 # something like this.
15
16 use JSON::RPC::Common::Procedure::Call;
17
18 # deserialize whatever json text you have into json data:
19 my $req = from_json($request_body);
20
21 # inflate it and get a call object:
22 my $call = JSON::RPC::Common::Procedure::Call->inflate($req);
23
24 warn $call->version;
25
26 # this will create a result object of the correct class/version/etc
27 # "value" is the return result, regardless of version
28 my $res = $call->return_result("value");
29
30 # finally, convert back to json text:
31 print to_json($res->deflate);
32
34 This module provides abstractions for JSON-RPC 1.0, 1.1 (both
35 variations) and 2.0 (formerly 1.2) Procedure Call and Procedure Return
36 objects (formerly known as request and result), along with error
37 objects. It also provides marshalling objects to convert the model
38 objects into JSON text and HTTP requests/responses.
39
40 This module does not concern itself with the transport layer at all, so
41 the JSON-RPC 1.1 and the alternative specification, which are very
42 different on that level are implemented with the same class.
43
45 While JSON-RPC 1.0 and JSON-RPC 2.0 are beautifully simple, the JSON-
46 RPC 1.1 working draft, is most definitely not. It is a convoluted
47 protocol, and also demands a lot more complexity from the responders on
48 the server side (server side introspection ("system.describe"), strange
49 things relating to positional vs. named params...).
50
51 Unfortunately it appears that JSON-RPC 1.1 is the most popular variant.
52
53 Since the client essentially chooses the version of the RPC to be used,
54 for public APIs I reccomend that all versions be supported, but be
55 aware that a 1.1-WD server "MUST" implement service description in
56 order to be in compliance.
57
58 Anyway, enough bitching. I suggest making your servers 1.0+2.0, and
59 your clients 2.0.
60
62 There are various classes provided by JSON::RPC::Common.
63
64 They are designed for high reusability. All the classes are transport
65 and representation agnostic except for JSON::RPC::Common::Marshal::Text
66 and JSON::RPC::Common::Marshal::HTTP which are completely optional.
67
68 JSON::RPC::Common::Procedure::Call
69 This class and its subclasses implement Procedure Calls (requests) for
70 JSON-RPC 1.0, 1.1WD, 1.1-alt and 2.0.
71
72 JSON::RPC::Common::Procedure::Return
73 This class and its subclasses implement Procedure Returns (results) for
74 JSON-RPC 1.0, 1.1WD, 1.1-alt and 2.0.
75
76 JSON::RPC::Common::Procedure::Return::Error
77 This class and its subclasses implement Procedure Return error objects
78 for JSON-RPC 1.0, 1.1WD, 1.1-alt and 2.0.
79
80 JSON::RPC::Common::Marshal::Text
81 A filter object that uses JSON to serialize procedure calls and returns
82 to JSON text, including JSON-RPC standard error handling for
83 deserialization failure.
84
85 JSON::RPC::Common::Marshal::HTTP
86 A subclass of JSON::RPC::Common::Marshal::Text with additional methods
87 for marshaling between HTTP::Requests and
88 JSON::RPC::Common::Procedure::Call and HTTP::Response and
89 JSON::RPC::Common::Procedure::Return.
90
91 Also knows how to handle JSON-RPC 1.1 "GET" encoded requests (for all
92 versions), providing RESTish call semantics.
93
95 · JSON::RPC::Common::Handler, a generic dispatch table based handler,
96 useful for when you don't want to just blindly call methods on
97 certain objects using "call" in JSON::RPC::Common::Procedure::Call.
98
99 · JSON::RPC::Common::Errors, a class that will provide dictionaries
100 of error codes for JSON-RPC 1.1 and 1.1-alt/2.0.
101
102 · An object model for JSON-RPC 1.1 service description.
103
104 SMD is required by most JSON-RPC 1.1 over HTTP clients.
105
106 Since this is generally static, for now you can write one manually,
107 see
108 <http://groups.google.com/group/json-rpc/web/simple-method-description-for-json-rpc-example>
109 for an example
110
111 · Moose class to SMD translator
112
113 · MooseX::Storage enabled objects can serialize themselves into JSON,
114 and should DWIM when used. JSON-RPC 1.0 class hints could be used
115 here too.
116
117 · Convert to Squirrel for smaller deps and faster load time. Need to
118 find a solution for roles and type constraints. Neither is relied
119 on heavily.
120
122 On the Intertubes
123 JSON-RPC 1.0 specification
124 <http://json-rpc.org/wiki/specification>
125
126 JSON-RPC 1.1 working draft
127 <http://json-rpc.org/wd/JSON-RPC-1-1-WD-20060807.html>
128
129 JSON-RPC 1.1 alternative specification proposal
130 <http://groups.google.com/group/json-rpc/web/json-rpc-1-1-alt>
131
132 JSON-RPC 2.0 specification proposal
133 <http://groups.google.com/group/json-rpc/web/json-rpc-1-2-proposal>
134
135 Simplified encoding of JSON-RPC over HTTP
136 <http://groups.google.com/group/json-rpc/web/json-rpc-over-http>
137
138 On the CPAN
139 JSON, JSON::RPC, RPC::JSON, HTTP::Engine, CGI::JSONRPC
140
142 Yuval Kogman <nothingmuch@woobling.org>
143
145 This software is copyright (c) 2014 by Yuval Kogman and others.
146
147 This is free software; you can redistribute it and/or modify it under
148 the same terms as the Perl 5 programming language system itself.
149
150
151
152perl v5.30.1 2020-01-30 JSON::RPC::Common(3)