JsonRpcContrib

JSON-RPC interface for Foswiki

Summary

This package implements a 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 well defined calling semantics for requests and responses. The interface will also take care that any received data is recoded to the server's character encoding. JSON-RPC is normally called as part of some JavaScript AJAX application.

JsonRpcContrib also comes with a jQuery plugin to simplify working with JSON-RPC. This is a simple wrapper around jQuery's own AJAX capabilities.

Registering JSON-RPC procedures

Foswiki plugins are able to register their own handler for a specific method in a given namespace, thus:

use Foswiki::Contrib::JsonRpcContrib ();

sub initPlugin {
    ...
    Foswiki::Contrib::JsonRpcContrib::registerMethod(
        "MyNamespace", 
        "someMethod", 
        \$jsonRpcSomeMethod
    );
    ...
}

# Plugin's implementation
sub jsonRpcSomeMethod {
    my ($session, $request) = @_;
    ...
   # Return some result
   return $result;
}

Handler functions

The handler function in your plugin takes two parameters, $session and $request. $session is a reference to the Foswiki session; most implementers should simply ignore this. $request is a reference to the JSON request object. The following methods are available on this object:

• param('param1') - returns the value of a single named parameter
• params() - returns a reference to the entire parameter hash
• method() - returns the method
• namespace() - returns the namespace

The handler function can return a scalar or a reference to an acyclic graph (a tree structure). The structure may contain blessed data (perl objects) if (and only if) those objects implement the TO_JSON method described in the documentation for the CPAN JSON module.

Errors can be signalled using a simple die. Such errors will be returned to the caller with an errorCode of 1. If you need to pass back extended error information, you will have to encode it in the die message.

Calling using a POST

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

https://outzenj.com/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"
}

Calling using jQuery

The jQuery plugin can be used by requesting it via %JQREQUIRE{"jsonrpc"}%. JSON-RPC can now be called 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) { ... }
  }
);

Error response

If the procedure fails for any reason the JSON response will have the format

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

The following error codes are defined:

• -32700: Parse error - Invalid JSON was received by the server.
• -32600: Invalid Request - The JSON sent is not a valid Request object, or request was not a POST.
• -32601: Method not found - The method does not exist / is not available.
• -32602: Invalid params - Invalid method parameter(s).
• -32603: Internal error - Internal JSON-RPC error.
• -32099 to -32000: Server error - Reserved for implementation-defined server-errors.
• 1: unknown error - a die in the handler will return this
• 401: access denied - returned if provided credentials are incorrect

Success response

If the call is successful the JSON response will be of the format:

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

Authentication

If there is an existing login session then JSON-RPC calls will be authenticated using that session. Alternatively, requests can be authenticated by passing in username and password URL parameters. It is strongly recommended that this is only done if the communications links is secure (https:), as these parameters are sent in plain text.

Extensions to the standard

JSON-RPC 2.0 normally only allows you 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 is most conveniently sent using URL parameters (as is the case for normal HTML forms).

Instead of requiring all form fields to be converted into a JSON-RPC request object on the client side, the JsonRpcContrib converts form data to a proper request object transparently. This way you can call a JSON-RPC function using a simple form submission from the client.

The called namespace and method can thus be specified much like a subject/verb url to a REST interface. These calls are equivalent:

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

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

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

You can also use an 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 type can easily be sent to the server using JQueryForm's $.ajaxSubmit() method.

If a namespace, method, or parameters are specified as part of a JSON-RPC request object as well as using URL parameters, the URL parameters take higher precedence and are 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. "Extensions Operation and Maintenance" Tab -> "Install, Update or Remove extensions" Tab. Click the "Search for Extensions" button. Enter part of the extension name or description and press search. Select the desired extension(s) and click install. If an extension is already installed, it will not show up in the search results.

You can also install from the shell by running the extension installer as the web server user: (Be sure to run as the webserver user, not as root!)

cd /path/to/foswiki
perl tools/extension_installer <NameOfExtension> 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 https://foswiki.org/Support/ManuallyInstallingExtensions for more help.

Dependencies

Change History