.\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "JSON::RPC::Common 3pm"
.TH JSON::RPC::Common 3pm "2020-06-23" "perl v5.30.3" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
JSON::RPC::Common \- Transport agnostic JSON RPC helper objects
.SH "VERSION"
.IX Header "VERSION"
version 0.11
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 3
\&        # 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);
.Ve
.SH "DESCRIPTION"
.IX Header "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 \s-1JSON\s0 text and \s-1HTTP\s0
requests/responses.
.PP
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.
.SH "RANT"
.IX Header "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 (\f(CW\*(C`system.describe\*(C'\fR), strange things relating to positional
vs. named params...).
.PP
Unfortunately it appears that JSON-RPC 1.1 is the most popular variant.
.PP
Since the client essentially chooses the version of the \s-1RPC\s0 to be used, for
public APIs I reccomend that all versions be supported, but be aware that a
1.1\-WD server \*(L"\s-1MUST\*(R"\s0 implement service description in order to be in
compliance.
.PP
Anyway, enough bitching. I suggest making your servers 1.0+2.0, and your
clients 2.0.
.SH "CLASSES"
.IX Header "CLASSES"
There are various classes provided by JSON::RPC::Common.
.PP
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.
.SS "JSON::RPC::Common::Procedure::Call"
.IX Subsection "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.
.SS "JSON::RPC::Common::Procedure::Return"
.IX Subsection "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.
.SS "JSON::RPC::Common::Procedure::Return::Error"
.IX Subsection "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.
.SS "JSON::RPC::Common::Marshal::Text"
.IX Subsection "JSON::RPC::Common::Marshal::Text"
A filter object that uses \s-1JSON\s0 to serialize procedure calls and returns to
\&\s-1JSON\s0 text, including JSON-RPC standard error handling for deserialization
failure.
.SS "JSON::RPC::Common::Marshal::HTTP"
.IX Subsection "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.
.PP
Also knows how to handle JSON-RPC 1.1 \f(CW\*(C`GET\*(C'\fR encoded requests (for all
versions), providing RESTish call semantics.
.SH "TODO"
.IX Header "TODO"
.IP "\(bu" 4
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
\&\*(L"call\*(R" in JSON::RPC::Common::Procedure::Call.
.IP "\(bu" 4
JSON::RPC::Common::Errors, a class that will provide dictionaries of error
codes for JSON-RPC 1.1 and 1.1\-alt/2.0.
.IP "\(bu" 4
An object model for JSON-RPC 1.1 service description.
.Sp
\&\s-1SMD\s0 is required by most JSON-RPC 1.1 over \s-1HTTP\s0 clients.
.Sp
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
.IP "\(bu" 4
Moose class to \s-1SMD\s0 translator
.IP "\(bu" 4
MooseX::Storage enabled objects can serialize themselves into \s-1JSON,\s0 and
should \s-1DWIM\s0 when used. JSON-RPC 1.0 class hints could be used here too.
.IP "\(bu" 4
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.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
.SS "On the Intertubes"
.IX Subsection "On the Intertubes"
.IP "JSON-RPC 1.0 specification" 4
.IX Item "JSON-RPC 1.0 specification"
<http://json\-rpc.org/wiki/specification>
.IP "JSON-RPC 1.1 working draft" 4
.IX Item "JSON-RPC 1.1 working draft"
<http://json\-rpc.org/wd/JSON\-RPC\-1\-1\-WD\-20060807.html>
.IP "JSON-RPC 1.1 alternative specification proposal" 4
.IX Item "JSON-RPC 1.1 alternative specification proposal"
<http://groups.google.com/group/json\-rpc/web/json\-rpc\-1\-1\-alt>
.IP "JSON-RPC 2.0 specification proposal" 4
.IX Item "JSON-RPC 2.0 specification proposal"
<http://groups.google.com/group/json\-rpc/web/json\-rpc\-1\-2\-proposal>
.IP "Simplified encoding of JSON-RPC over \s-1HTTP\s0" 4
.IX Item "Simplified encoding of JSON-RPC over HTTP"
<http://groups.google.com/group/json\-rpc/web/json\-rpc\-over\-http>
.SS "On the \s-1CPAN\s0"
.IX Subsection "On the CPAN"
\&\s-1JSON\s0, \s-1JSON::RPC\s0, \s-1RPC::JSON\s0, HTTP::Engine, \s-1CGI::JSONRPC\s0
.SH "AUTHOR"
.IX Header "AUTHOR"
Yuval Kogman <nothingmuch@woobling.org>
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
This software is copyright (c) 2014 by Yuval Kogman and others.
.PP
This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.