JsonRpcContrib

JSON-RPC interface for Foswiki

Summary

This package implements an JSON-RPC 2.0 protocol to interface with Foswiki and its plugins. In contrast to the normal REST interface of Foswiki, a JSON-RPC interface offers a well defined calling semantics for requests and responses. The interface will also take care that any received data is recoded to the site's character encoding. JSON-RPC is normally called as part of some JavaScript ajax application. JsonRpcContrib also comes with a jQuery plugin to ease sending JSON-RPC. This is a simple wrapper around jQuery's own ajax capabilities which in addition takes care calls are well-formed.

Registering procedures

Foswiki plugins are able to register their own handler to be responsible for a specific method in a given namespace, like this:

use Foswiki::Contrib::JsonRpcContrib ();
Foswiki::Contrib::JsonRpcContrib::registerMethod(
  "MyNamespace", 
  "someMethod", 
  \$jsonRpcSomeMethod
);

sub jsonRpcSomeMethod {
  my ($session, $request) = @_;

...
}

Calling procedures

Once a handler is registered it may be called using an URL of the format

https://biostat.app.vumc.org/wiki/bin/jsonrpc/MyNamespace

... while POSTing a JSON encoded request according to the JSON-RPC 2.0 specification, like,

{
  jsonrpc: "2.0", 
  method: "someMethod", 
  params: {
     topic: "Web.Topic",
     ...
     param1: "value1",
     param2: "value2",
     ...
  }, 
  id: "caller's id"
}

Optionally, the jQuery plugin can be used by requesting it via %!JQREQUIRE{"jsonrpc"}%. JSON-RPC can now be issued like this:

$.jsonRpc(
  endpoint, /* %SCRIPTURL{"jsonrpc"}% */
  {
    namespace: "MyNamespace",
    method: "someMethod",
    id: "some caller's id",
    params: {
     topic: "Web.Topic",
     ...
     param1: "value1",
     param2: "value2", 
    },
    beforeSend: function(xhr) { ... },
    error: function(jsonResponse, textStatus, xhr) { ... },
    success: function(jsonResponse, textStatus, xhr) { ... }
  }
);

In case of an error the JSON response will have the format

{
  jsonrpc: "2.0",
  error: {
    code: errorCode,
    message: "error description"
  },
  id: "caller's id"
}

In case of a successfull call the JSON response will be of the format

{
   jsonrpc: "2.0",
   result: some-result-object,
   id: "caller's id"
}

Extensions to the standard

JSON-RPC 2.0 normally only allows to pass parameters to a remote procedure using a well formed request object as described above. However in real-live web applications data to be transmitted to a specific endpoint using URL parameter as is the case for a normal HTML form. Instead of requiring all form fields to be converted into a JSON-RPC request object on the client side the Foswiki server interface converts data transmitted this way to a proper request object transparently. This way any JSON-RPC call feels much like a standard REST interface.

The called namespace and method can thus be specified much like a subject/verb url to a REST interface, that is these calls are equivalent:

$.jsonRpc(
  "%SCRIPTURL{"jsonrpc"}%" 
  namespace: "MyNamespace",
  method: "someMethod",
  ...
);

$.jsonRpc(
  "%SCRIPTURL{"jsonrpc"}%/MyNamespace",
  method: "someMethod",
  ...
);

$.jsonRpc(
  "%SCRIPTURL{"jsonrpc"}%/MyNamespace/someMethod" 
  ...
);

As well as using a proper HTML form

<form action="%SCRIPTURL{"jsonrpc"}%" method="post">
<input type="hidden" name="namespace" value="MyNamespace" />
<input type="hidden" name="method" value="someMethod" />
...
</form>

<form action="%SCRIPTURL{"jsonrpc"}%/Mynamespace" method="post">
<input type="hidden" name="method" value="someMethod" />
...
</form>

<form action="%SCRIPTURL{"jsonrpc"}%/Mynamespace/someMethod" method="post">
...
</form>

Forms of this kind can be send over to the backend using JQueryForm's $.ajaxSubmit() method without a problem.

In case a namespace, method or parameters are specified as part of a JSON-RPC request object as well as using URL parameters, the latter take higher precedence and are effectively merged into the request object.

Installation Instructions

You do not need to install anything in the browser to use this extension. The following instructions are for the administrator who installs the extension on the server.

Open configure, and open the "Extensions" section. Use "Find More Extensions" to get a list of available extensions. Select "Install".

If you have any problems, or if the extension isn't available in configure, then you can still install manually from the command-line. See http://foswiki.org/Support/ManuallyInstallingExtensions for more help.

Info

Author(s):	Michael Daum
Copyright:	© 2011-2012 Michael Daum http://michaeldaumconsulting.com
License:	GPL (Gnu General Public License)
Release:	1.21
Version:	14609 (2012-04-16)
Change History:
16 Apr 2012:	fixing jsonrpc for apache's suexec
10 Jan 2012:	fixed perl dependencies; added redirectto url parameter similar to the standard foswiki rest handler
10 May 2011:	fixed jsonrpc script to work on old foswikis; fixed multi-value params; fixed compatibility with various JSON cpan libraries
29 Apr 2011:	initial release
Dependencies:	Name Version Description JSON >=2.17 Required. Available from the CPAN archive. JSON::XS >=2.27 Required. Available from the CPAN archive.
Home page:	Foswiki:Extensions/JsonRpcContrib
Support:	Foswiki:Support/JsonRpcContrib