Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
JSON::RPC::Common(3)  User Contributed Perl Documentation JSON::RPC::Common(3)

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

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.

perl v5.24.1			  2014-02-28		  JSON::RPC::Common(3)

NAME | VERSION | SYNOPSIS | DESCRIPTION | RANT | CLASSES | TODO | SEE ALSO | AUTHOR | COPYRIGHT AND LICENSE

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=JSON::RPC::Common&sektion=3&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help