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; }
$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
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.
https://www.mitomap.org/foswiki/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" }
%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) { ... } } );
{ jsonrpc: "2.0", error: { code: errorCode, message: "error description" }, id: "caller's id" }The following error codes are defined:
die
in the handler will return this
{ jsonrpc: "2.0", result: some-result-object, id: "caller's id" }
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.
$.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.
cd /path/to/foswiki perl tools/extension_installer <NameOfExtension> installIf 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.
Name | Version | Description |
---|---|---|
JSON | >=2.59 | Required. |
31 Jan 2022: (2.30) | added foswiki.jsonRpc() api |
08 Apr 2017: (2.28) | Foswikitask:Item14366: Reorder initialization to allow local CGI::Carp. |
26 Nov 2016: (2.27) | Released with Foswiki 2.1.3. Foswikitask:Item14204: redirectto incorrectly encodes Anchors. |
04 Apr 2016: (2.26) | Foswikitask:Item14025: Fix issues with JSON::XS 3.02 in some environments. |
18 Mar 2016: (2.25) | Foswikitask:Item14011: Make sure HTTP2 is always compressing. |
03 Feb 2016: (2.24) | Foswikitask:Item13405: Add NFC normalization of Unicode strings. |
14 Jul 2015: (2.23) | fixed encoding of compressed responses Foswikitask:Item13521 |
14 Jun 2015: (2.22) | Release with Foswiki 2.0. Foswikitask:Item13378: Implement UNICODE support, Foswikitask:Item13323: Use /usr/bin/env perl. Foswikitask:Item13412: Don't utf-8 encode response |
29 Jan 2015: | Foswikitask:Item13238: fix content-type of response |
17 Dec 2014: | Foswikitask:Item13164: added support for gzip compression of http response Foswikitask:Item13125: CGI changes for multi_param calls Foswikitask:Item13065: Log jsonrpc events to Foswiki event.log |
28 Aug 2014: | don't use DEBUG constant to toggle local debug messages as it conflicts with Assert.pm |
11 Dec 2013: | removed dependency on JSON::XS |
30 May 2013: | added support for serialising objects, and rewrote some of the documentation (Foswiki:Main/CrawfordCurrie) |
20 Mar 2013: | added feature to define handlers in LocalSite.cfg (Config.spec) so that pure contribs can implement backends now |
1 Oct 2012: | added the async flag to the $.jsonRpc frontend to $.ajax |
2 Aug 2012: | fixed json2 not loaded in IE7 (Foswiki:Main/JanKrueger) |
16 Apr 2012: | fixed 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 |
Author | Michael Daum |
Version | 2.30 |
Release | 31 Jan 2022 |
Description | JSON-RPC interface for Foswiki |
Repository | https://github.com/foswiki/distro |
Copyright | © 2011-2022 Michael Daum and Foswiki Contributors |
License | GPL (Gnu General Public License) |
Home | http://foswiki.org/Extensions/JsonRpcContrib |
Support | Foswiki:Support/JsonRpcContrib |