Difference: JsonRpcContrib (1 vs. 18)

Revision 18
11 Oct 2016 - Main.AdminUser
 

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:

http://www.leader.it/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.
  • -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. 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.

Dependencies

NameVersionDescription
JSON>=2.59Required.

Change History

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

META FORM name="PackageForm"
FORM FIELD Author Author Michael Daum
FORM FIELD Version Version 2.26
FORM FIELD Release Release 4 Apr 2016
FORM FIELD Description Description JSON-RPC interface for Foswiki
FORM FIELD Repository Repository https://github.com/foswiki/distro
FORM FIELD Copyright Copyright © 2011-2016 Michael Daum http://michaeldaumconsulting.com and Foswiki Contributors
FORM FIELD License License GPL (Gnu General Public License)
FORM FIELD Home Home http://foswiki.org/Extensions/JsonRpcContrib
FORM FIELD Support Support Foswiki:Support/JsonRpcContrib
META FILEATTACHMENT attachment="Makefile" attr="" comment="" date="1462075766" name="Makefile" size="136" user="BaseUserMapping_333" version="12"
META FILEATTACHMENT attachment="jquery.jsonrpc.js" attr="" comment="" date="1462075766" name="jquery.jsonrpc.js" size="1106" user="BaseUserMapping_333" version="12"
META FILEATTACHMENT attachment="jquery.jsonrpc.js.gz" attr="" comment="" date="1462075766" name="jquery.jsonrpc.js.gz" size="460" user="BaseUserMapping_333" version="12"
META FILEATTACHMENT attachment="jquery.jsonrpc.uncompressed.js" attr="" comment="" date="1462075766" name="jquery.jsonrpc.uncompressed.js" size="1720" user="BaseUserMapping_333" version="12"
META FILEATTACHMENT attachment="json2.js" attr="" comment="" date="1462075766" name="json2.js" size="3388" user="BaseUserMapping_333" version="12"
META FILEATTACHMENT attachment="json2.js.gz" attr="" comment="" date="1462075766" name="json2.js.gz" size="1343" user="BaseUserMapping_333" version="12"
META FILEATTACHMENT attachment="json2.uncompressed.js" attr="" comment="" date="1462075766" name="json2.uncompressed.js" size="17409" user="BaseUserMapping_333" version="12"
Revision 17
11 Oct 2016 - Main.AdminUser
 

JsonRpcContrib

Changed:
<
<
%SHORTDESCRIPTION%
>
>
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:

http://www.leader.it/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.
  • -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

Deleted:
<
<
  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.
Changed:
<
<

Info

 
Changed:
<
<
Author(s): Michael Daum
Copyright: © 2011-2014 Michael Daum http://michaeldaumconsulting.com
License: GPL (Gnu General Public License)
Release: 2.12
Version: 2.12
Change History:
<-- versions below in reverse order -->
 
>
>

Change History

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.
Added:
>
>
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
Deleted:
<
<
Dependencies:
NameVersionDescription
JSON>=2.59Required. Available from the CPAN archive.
Home page: Foswiki:Extensions/JsonRpcContrib
Support: Foswiki:Support/JsonRpcContrib
 
Changed:
<
<
META FILEATTACHMENT attachment="Makefile" attr="" comment="" date="1409225136" name="Makefile" size="136" user="BaseUserMapping_333" version="11"
META FILEATTACHMENT attachment="jquery.jsonrpc.js" attr="" comment="" date="1409225136" name="jquery.jsonrpc.js" size="1099" user="BaseUserMapping_333" version="11"
META FILEATTACHMENT attachment="jquery.jsonrpc.js.gz" attr="" comment="" date="1409225136" name="jquery.jsonrpc.js.gz" size="476" user="BaseUserMapping_333" version="11"
META FILEATTACHMENT attachment="jquery.jsonrpc.uncompressed.js" attr="" comment="" date="1409225136" name="jquery.jsonrpc.uncompressed.js" size="1713" user="BaseUserMapping_333" version="11"
META FILEATTACHMENT attachment="json2.js" attr="" comment="" date="1409225136" name="json2.js" size="3388" user="BaseUserMapping_333" version="11"
META FILEATTACHMENT attachment="json2.js.gz" attr="" comment="" date="1409225136" name="json2.js.gz" size="1352" user="BaseUserMapping_333" version="11"
META FILEATTACHMENT attachment="json2.uncompressed.js" attr="" comment="" date="1409225136" name="json2.uncompressed.js" size="17413" user="BaseUserMapping_333" version="11"
>
>
META FORM name="PackageForm"
FORM FIELD Author Author Michael Daum
FORM FIELD Version Version 2.26
FORM FIELD Release Release 4 Apr 2016
FORM FIELD Description Description JSON-RPC interface for Foswiki
FORM FIELD Repository Repository https://github.com/foswiki/distro
FORM FIELD Copyright Copyright © 2011-2016 Michael Daum http://michaeldaumconsulting.com and Foswiki Contributors
Added:
>
>
FORM FIELD License License GPL (Gnu General Public License)
FORM FIELD Home Home http://foswiki.org/Extensions/JsonRpcContrib
FORM FIELD Support Support Foswiki:Support/JsonRpcContrib
META FILEATTACHMENT attachment="Makefile" attr="" comment="" date="1462075766" name="Makefile" size="136" user="BaseUserMapping_333" version="12"
META FILEATTACHMENT attachment="jquery.jsonrpc.js" attr="" comment="" date="1462075766" name="jquery.jsonrpc.js" size="1106" user="BaseUserMapping_333" version="12"
META FILEATTACHMENT attachment="jquery.jsonrpc.js.gz" attr="" comment="" date="1462075766" name="jquery.jsonrpc.js.gz" size="460" user="BaseUserMapping_333" version="12"
META FILEATTACHMENT attachment="jquery.jsonrpc.uncompressed.js" attr="" comment="" date="1462075766" name="jquery.jsonrpc.uncompressed.js" size="1720" user="BaseUserMapping_333" version="12"
META FILEATTACHMENT attachment="json2.js" attr="" comment="" date="1462075766" name="json2.js" size="3388" user="BaseUserMapping_333" version="12"
META FILEATTACHMENT attachment="json2.js.gz" attr="" comment="" date="1462075766" name="json2.js.gz" size="1343" user="BaseUserMapping_333" version="12"
META FILEATTACHMENT attachment="json2.uncompressed.js" attr="" comment="" date="1462075766" name="json2.uncompressed.js" size="17409" user="BaseUserMapping_333" version="12"
 
Revision 16
25 Sep 2014 - Main.AdminUser
 

JsonRpcContrib

%SHORTDESCRIPTION%

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:

http://www.leader.it/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.
  • -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. 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

<-- 
  • Set SHORTDESCRIPTION = JSON-RPC interface for Foswiki
-->

Author(s): Michael Daum
Copyright: © 2011-2014 Michael Daum http://michaeldaumconsulting.com
License: GPL (Gnu General Public License)
Release: 2.12
Version: 2.12
Change History:
<-- versions below in reverse order -->
 
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
Dependencies:
NameVersionDescription
JSON>=2.59Required. Available from the CPAN archive.
Home page: Foswiki:Extensions/JsonRpcContrib
Support: Foswiki:Support/JsonRpcContrib

META FILEATTACHMENT attachment="Makefile" attr="" comment="" date="1409225136" name="Makefile" size="136" user="BaseUserMapping_333" version="11"
META FILEATTACHMENT attachment="jquery.jsonrpc.js" attr="" comment="" date="1409225136" name="jquery.jsonrpc.js" size="1099" user="BaseUserMapping_333" version="11"
META FILEATTACHMENT attachment="jquery.jsonrpc.js.gz" attr="" comment="" date="1409225136" name="jquery.jsonrpc.js.gz" size="476" user="BaseUserMapping_333" version="11"
META FILEATTACHMENT attachment="jquery.jsonrpc.uncompressed.js" attr="" comment="" date="1409225136" name="jquery.jsonrpc.uncompressed.js" size="1713" user="BaseUserMapping_333" version="11"
META FILEATTACHMENT attachment="json2.js" attr="" comment="" date="1409225136" name="json2.js" size="3388" user="BaseUserMapping_333" version="11"
META FILEATTACHMENT attachment="json2.js.gz" attr="" comment="" date="1409225136" name="json2.js.gz" size="1352" user="BaseUserMapping_333" version="11"
META FILEATTACHMENT attachment="json2.uncompressed.js" attr="" comment="" date="1409225136" name="json2.uncompressed.js" size="17413" user="BaseUserMapping_333" version="11"
Revision 15
25 Sep 2014 - Main.AdminUser
 

JsonRpcContrib

%SHORTDESCRIPTION%

On this page:

Summary

Changed:
<
<
This package implements an JSON-RPC 2.0 protocol to interface
>
>
This package implements a JSON-RPC 2.0 protocol to interface
  with Foswiki and its plugins.
Deleted:
<
<
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.
 
Changed:
<
<

Registering procedures

Foswiki plugins are able to register their own handler to be responsible for a specific method in a given namespace, like this:
>
>
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
Added:
>
>
to the server's character encoding. JSON-RPC is normally called as part of some JavaScript AJAX application.
 
Added:
>
>
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 ();
Deleted:
<
<
Foswiki::Contrib::JsonRpcContrib::registerMethod( "MyNamespace", "someMethod", \$jsonRpcSomeMethod );
 
Changed:
<
<
sub jsonRpcSomeMethod { my ($session, $request) = @_;
>
>
sub initPlugin { ...
Added:
>
>
Foswiki::Contrib::JsonRpcContrib::registerMethod( "MyNamespace", "someMethod", \$jsonRpcSomeMethod ); ... }
 
Changed:
<
<
...
>
>
# Plugin's implementation
Added:
>
>
sub jsonRpcSomeMethod { my ($session, $request) = @_; ... # Return some result return $result;
  }
Changed:
<
<

Calling procedures

>
>

Handler functions

Added:
>
>
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.
 
Changed:
<
<
Once a handler is registered it may be called using an URL of the format
>
>
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.
 
Added:
>
>

Calling using a POST

Once a handler is registered it may be called using an URL of the format:
  http://www.leader.it/bin/jsonrpc/MyNamespace
Changed:
<
<
... while POSTing a JSON encoded request according to the JSON-RPC 2.0 specification,
>
>
... 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"
}
Changed:
<
<
Optionally, the jQuery plugin can be used by requesting it via %!JQREQUIRE{"jsonrpc"}%. JSON-RPC can now be issued like this:
>
>

Calling using jQuery

The jQuery plugin can be used by requesting it via
Added:
>
>
%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) { ... }
  }
);
Changed:
<
<
In case of an error the JSON response will have the format
>
>

Error response

 
Added:
>
>
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"
}
Changed:
<
<
In case of a successfull call the JSON response will be of the format
>
>
The following error codes are defined:
Added:
>
>
  • -32700: Parse error - Invalid JSON was received by the server.
  • -32600: Invalid Request - The JSON sent is not a valid Request object.
  • -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
 
Added:
>
>

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"
}
Added:
>
>

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

Changed:
<
<
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.
>
>
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
Added:
>
>
a specific endpoint is most conveniently sent using URL parameters (as is the case for normal HTML forms).
 
Changed:
<
<
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:
>
>
Instead of requiring all form fields to be converted into a JSON-RPC request object on the client side, the JsonRpcContrib
Added:
>
>
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.
 
Added:
>
>
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" 
  ...
);
Changed:
<
<
As well as using a proper HTML form
>
>
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>
Changed:
<
<
Forms of this kind can be send over to the backend using JQueryForm's $.ajaxSubmit() method without a problem.
>
>
Forms of this type can easily be sent to the server using JQueryForm's $.ajaxSubmit() method.
 
Changed:
<
<
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.
>
>
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. 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

<-- 
  • Set SHORTDESCRIPTION = JSON-RPC interface for Foswiki
-->
Changed:
<
<
Author(s): Michael Daum
Copyright: © 2011-2013 Michael Daum http://michaeldaumconsulting.com
>
>
Author(s): Michael Daum
Copyright: © 2011-2014 Michael Daum http://michaeldaumconsulting.com
 
License: GPL (Gnu General Public License)
Changed:
<
<
Release: 2.00
Version: 2.00
>
>
Release: 2.12
Version: 2.12
 
Change History:
<-- versions below in reverse order -->
 
Added:
>
>
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
Changed:
<
<
Dependencies:
NameVersionDescription
JSON>=2.17Required. Available from the CPAN archive.
JSON::XS>=2.27Required. Available from the CPAN archive.
>
>
Dependencies:
NameVersionDescription
JSON>=2.59Required. Available from the CPAN archive.
 
Home page: Foswiki:Extensions/JsonRpcContrib
Support: Foswiki:Support/JsonRpcContrib
Changed:
<
<
META FILEATTACHMENT attachment="json2.uncompressed.js" attr="" comment="" date="1364488906" name="json2.uncompressed.js" size="17413" user="BaseUserMapping_333" version="10"
META FILEATTACHMENT attachment="jquery.jsonrpc.uncompressed.js" attr="" comment="" date="1364488906" name="jquery.jsonrpc.uncompressed.js" size="1713" user="BaseUserMapping_333" version="10"
META FILEATTACHMENT attachment="json2.js" attr="" comment="" date="1364488906" name="json2.js" size="3377" user="BaseUserMapping_333" version="10"
META FILEATTACHMENT attachment="Makefile" attr="" comment="" date="1364488906" name="Makefile" size="136" user="BaseUserMapping_333" version="10"
META FILEATTACHMENT attachment="jquery.jsonrpc.js.gz" attr="" comment="" date="1364488906" name="jquery.jsonrpc.js.gz" size="420" user="BaseUserMapping_333" version="10"
META FILEATTACHMENT attachment="json2.js.gz" attr="" comment="" date="1364488906" name="json2.js.gz" size="1333" user="BaseUserMapping_333" version="10"
META FILEATTACHMENT attachment="jquery.jsonrpc.js" attr="" comment="" date="1364488906" name="jquery.jsonrpc.js" size="821" user="BaseUserMapping_333" version="10"
>
>
META FILEATTACHMENT attachment="Makefile" attr="" comment="" date="1409225136" name="Makefile" size="136" user="BaseUserMapping_333" version="11"
META FILEATTACHMENT attachment="jquery.jsonrpc.js" attr="" comment="" date="1409225136" name="jquery.jsonrpc.js" size="1099" user="BaseUserMapping_333" version="11"
META FILEATTACHMENT attachment="jquery.jsonrpc.js.gz" attr="" comment="" date="1409225136" name="jquery.jsonrpc.js.gz" size="476" user="BaseUserMapping_333" version="11"
META FILEATTACHMENT attachment="jquery.jsonrpc.uncompressed.js" attr="" comment="" date="1409225136" name="jquery.jsonrpc.uncompressed.js" size="1713" user="BaseUserMapping_333" version="11"
META FILEATTACHMENT attachment="json2.js" attr="" comment="" date="1409225136" name="json2.js" size="3388" user="BaseUserMapping_333" version="11"
META FILEATTACHMENT attachment="json2.js.gz" attr="" comment="" date="1409225136" name="json2.js.gz" size="1352" user="BaseUserMapping_333" version="11"
META FILEATTACHMENT attachment="json2.uncompressed.js" attr="" comment="" date="1409225136" name="json2.uncompressed.js" size="17413" user="BaseUserMapping_333" version="11"
 
Revision 14
09 May 2013 - Main.AdminUser
 

JsonRpcContrib

%SHORTDESCRIPTION%

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

http://www.leader.it/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

<-- 
  • Set SHORTDESCRIPTION = JSON-RPC interface for Foswiki
-->

Author(s): Michael Daum
Copyright: © 2011-2013 Michael Daum http://michaeldaumconsulting.com
License: GPL (Gnu General Public License)
Release: 2.00
Version: 2.00
Change History:
<-- versions below in reverse order -->
 
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
Dependencies:
NameVersionDescription
JSON>=2.17Required. Available from the CPAN archive.
JSON::XS>=2.27Required. Available from the CPAN archive.
Home page: Foswiki:Extensions/JsonRpcContrib
Support: Foswiki:Support/JsonRpcContrib

META FILEATTACHMENT attachment="json2.uncompressed.js" attr="" comment="" date="1364488906" name="json2.uncompressed.js" size="17413" user="BaseUserMapping_333" version="10"
META FILEATTACHMENT attachment="jquery.jsonrpc.uncompressed.js" attr="" comment="" date="1364488906" name="jquery.jsonrpc.uncompressed.js" size="1713" user="BaseUserMapping_333" version="10"
META FILEATTACHMENT attachment="json2.js" attr="" comment="" date="1364488906" name="json2.js" size="3377" user="BaseUserMapping_333" version="10"
META FILEATTACHMENT attachment="Makefile" attr="" comment="" date="1364488906" name="Makefile" size="136" user="BaseUserMapping_333" version="10"
META FILEATTACHMENT attachment="jquery.jsonrpc.js.gz" attr="" comment="" date="1364488906" name="jquery.jsonrpc.js.gz" size="420" user="BaseUserMapping_333" version="10"
META FILEATTACHMENT attachment="json2.js.gz" attr="" comment="" date="1364488906" name="json2.js.gz" size="1333" user="BaseUserMapping_333" version="10"
META FILEATTACHMENT attachment="jquery.jsonrpc.js" attr="" comment="" date="1364488906" name="jquery.jsonrpc.js" size="821" user="BaseUserMapping_333" version="10"
Revision 13
09 May 2013 - Main.AdminUser
 

JsonRpcContrib

%SHORTDESCRIPTION%

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

http://www.leader.it/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

<-- 
  • Set SHORTDESCRIPTION = JSON-RPC interface for Foswiki
-->

Author(s): Michael Daum
Changed:
<
<
Copyright: © 2011-2012 Michael Daum http://michaeldaumconsulting.com
>
>
Copyright: © 2011-2013 Michael Daum http://michaeldaumconsulting.com
 
License: GPL (Gnu General Public License)
Changed:
<
<
Release: 1.30
Version: 15467 (2012-10-01)
>
>
Release: 2.00
Version: 2.00
 
Change History:
<-- versions below in reverse order -->
 
Added:
>
>
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
Dependencies:
NameVersionDescription
JSON>=2.17Required. Available from the CPAN archive.
JSON::XS>=2.27Required. Available from the CPAN archive.
Home page: Foswiki:Extensions/JsonRpcContrib
Support: Foswiki:Support/JsonRpcContrib
Changed:
<
<
META FILEATTACHMENT attachment="json2.uncompressed.js" attr="" comment="" date="1349106887" name="json2.uncompressed.js" size="17413" user="BaseUserMapping_333" version="9"
META FILEATTACHMENT attachment="jquery.jsonrpc.uncompressed.js" attr="" comment="" date="1349106887" name="jquery.jsonrpc.uncompressed.js" size="1713" user="BaseUserMapping_333" version="9"
META FILEATTACHMENT attachment="json2.js" attr="" comment="" date="1349106887" name="json2.js" size="3377" user="BaseUserMapping_333" version="9"
META FILEATTACHMENT attachment="Makefile" attr="" comment="" date="1349106887" name="Makefile" size="136" user="BaseUserMapping_333" version="9"
META FILEATTACHMENT attachment="jquery.jsonrpc.js.gz" attr="" comment="" date="1349106887" name="jquery.jsonrpc.js.gz" size="438" user="BaseUserMapping_333" version="9"
META FILEATTACHMENT attachment="json2.js.gz" attr="" comment="" date="1349106887" name="json2.js.gz" size="1342" user="BaseUserMapping_333" version="9"
META FILEATTACHMENT attachment="jquery.jsonrpc.js" attr="" comment="" date="1349106887" name="jquery.jsonrpc.js" size="821" user="BaseUserMapping_333" version="9"
>
>
META FILEATTACHMENT attachment="json2.uncompressed.js" attr="" comment="" date="1364488906" name="json2.uncompressed.js" size="17413" user="BaseUserMapping_333" version="10"
META FILEATTACHMENT attachment="jquery.jsonrpc.uncompressed.js" attr="" comment="" date="1364488906" name="jquery.jsonrpc.uncompressed.js" size="1713" user="BaseUserMapping_333" version="10"
META FILEATTACHMENT attachment="json2.js" attr="" comment="" date="1364488906" name="json2.js" size="3377" user="BaseUserMapping_333" version="10"
META FILEATTACHMENT attachment="Makefile" attr="" comment="" date="1364488906" name="Makefile" size="136" user="BaseUserMapping_333" version="10"
META FILEATTACHMENT attachment="jquery.jsonrpc.js.gz" attr="" comment="" date="1364488906" name="jquery.jsonrpc.js.gz" size="420" user="BaseUserMapping_333" version="10"
META FILEATTACHMENT attachment="json2.js.gz" attr="" comment="" date="1364488906" name="json2.js.gz" size="1333" user="BaseUserMapping_333" version="10"
META FILEATTACHMENT attachment="jquery.jsonrpc.js" attr="" comment="" date="1364488906" name="jquery.jsonrpc.js" size="821" user="BaseUserMapping_333" version="10"
 
Revision 12
17 Nov 2012 - Main.AdminUser
 

JsonRpcContrib

%SHORTDESCRIPTION%

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

http://www.leader.it/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

<-- 
  • Set SHORTDESCRIPTION = JSON-RPC interface for Foswiki
-->

Author(s): Michael Daum
Copyright: © 2011-2012 Michael Daum http://michaeldaumconsulting.com
License: GPL (Gnu General Public License)
Release: 1.30
Version: 15467 (2012-10-01)
Change History:
<-- versions below in reverse order -->
 
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
Dependencies:
NameVersionDescription
JSON>=2.17Required. Available from the CPAN archive.
JSON::XS>=2.27Required. Available from the CPAN archive.
Home page: Foswiki:Extensions/JsonRpcContrib
Support: Foswiki:Support/JsonRpcContrib

META FILEATTACHMENT attachment="json2.uncompressed.js" attr="" comment="" date="1349106887" name="json2.uncompressed.js" size="17413" user="BaseUserMapping_333" version="9"
META FILEATTACHMENT attachment="jquery.jsonrpc.uncompressed.js" attr="" comment="" date="1349106887" name="jquery.jsonrpc.uncompressed.js" size="1713" user="BaseUserMapping_333" version="9"
META FILEATTACHMENT attachment="json2.js" attr="" comment="" date="1349106887" name="json2.js" size="3377" user="BaseUserMapping_333" version="9"
META FILEATTACHMENT attachment="Makefile" attr="" comment="" date="1349106887" name="Makefile" size="136" user="BaseUserMapping_333" version="9"
META FILEATTACHMENT attachment="jquery.jsonrpc.js.gz" attr="" comment="" date="1349106887" name="jquery.jsonrpc.js.gz" size="438" user="BaseUserMapping_333" version="9"
META FILEATTACHMENT attachment="json2.js.gz" attr="" comment="" date="1349106887" name="json2.js.gz" size="1342" user="BaseUserMapping_333" version="9"
META FILEATTACHMENT attachment="jquery.jsonrpc.js" attr="" comment="" date="1349106887" name="jquery.jsonrpc.js" size="821" user="BaseUserMapping_333" version="9"
Revision 11
17 Nov 2012 - Main.AdminUser
 

JsonRpcContrib

%SHORTDESCRIPTION%

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

http://www.leader.it/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

<-- 
  • Set SHORTDESCRIPTION = JSON-RPC interface for Foswiki
-->

Author(s): Michael Daum
Copyright: © 2011-2012 Michael Daum http://michaeldaumconsulting.com
License: GPL (Gnu General Public License)
Release: 1.30
Version: 15467 (2012-10-01)
Change History:
<-- versions below in reverse order -->
 
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
Dependencies:
NameVersionDescription
JSON>=2.17Required. Available from the CPAN archive.
JSON::XS>=2.27Required. Available from the CPAN archive.
Home page: Foswiki:Extensions/JsonRpcContrib
Support: Foswiki:Support/JsonRpcContrib
Changed:
<
<
META FILEATTACHMENT attachment="json2.uncompressed.js" attr="" comment="" date="1349106887" name="json2.uncompressed.js" size="17413" user="BaseUserMapping_333" version="8"
META FILEATTACHMENT attachment="jquery.jsonrpc.uncompressed.js" attr="" comment="" date="1349106887" name="jquery.jsonrpc.uncompressed.js" size="1713" user="BaseUserMapping_333" version="8"
META FILEATTACHMENT attachment="json2.js" attr="" comment="" date="1349106887" name="json2.js" size="3377" user="BaseUserMapping_333" version="8"
META FILEATTACHMENT attachment="Makefile" attr="" comment="" date="1349106887" name="Makefile" size="136" user="BaseUserMapping_333" version="8"
META FILEATTACHMENT attachment="jquery.jsonrpc.js.gz" attr="" comment="" date="1349106887" name="jquery.jsonrpc.js.gz" size="438" user="BaseUserMapping_333" version="8"
META FILEATTACHMENT attachment="json2.js.gz" attr="" comment="" date="1349106887" name="json2.js.gz" size="1342" user="BaseUserMapping_333" version="8"
META FILEATTACHMENT attachment="jquery.jsonrpc.js" attr="" comment="" date="1349106887" name="jquery.jsonrpc.js" size="821" user="BaseUserMapping_333" version="8"
>
>
META FILEATTACHMENT attachment="json2.uncompressed.js" attr="" comment="" date="1349106887" name="json2.uncompressed.js" size="17413" user="BaseUserMapping_333" version="9"
META FILEATTACHMENT attachment="jquery.jsonrpc.uncompressed.js" attr="" comment="" date="1349106887" name="jquery.jsonrpc.uncompressed.js" size="1713" user="BaseUserMapping_333" version="9"
META FILEATTACHMENT attachment="json2.js" attr="" comment="" date="1349106887" name="json2.js" size="3377" user="BaseUserMapping_333" version="9"
META FILEATTACHMENT attachment="Makefile" attr="" comment="" date="1349106887" name="Makefile" size="136" user="BaseUserMapping_333" version="9"
META FILEATTACHMENT attachment="jquery.jsonrpc.js.gz" attr="" comment="" date="1349106887" name="jquery.jsonrpc.js.gz" size="438" user="BaseUserMapping_333" version="9"
META FILEATTACHMENT attachment="json2.js.gz" attr="" comment="" date="1349106887" name="json2.js.gz" size="1342" user="BaseUserMapping_333" version="9"
META FILEATTACHMENT attachment="jquery.jsonrpc.js" attr="" comment="" date="1349106887" name="jquery.jsonrpc.js" size="821" user="BaseUserMapping_333" version="9"
 
Revision 10
17 Nov 2012 - Main.AdminUser
 

JsonRpcContrib

%SHORTDESCRIPTION%

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

http://www.leader.it/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

<-- 
  • Set SHORTDESCRIPTION = JSON-RPC interface for Foswiki
-->

Author(s): Michael Daum
Copyright: © 2011-2012 Michael Daum http://michaeldaumconsulting.com
License: GPL (Gnu General Public License)
Release: 1.30
Version: 15467 (2012-10-01)
Change History:
<-- versions below in reverse order -->
 
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
Dependencies:
NameVersionDescription
JSON>=2.17Required. Available from the CPAN archive.
JSON::XS>=2.27Required. Available from the CPAN archive.
Home page: Foswiki:Extensions/JsonRpcContrib
Support: Foswiki:Support/JsonRpcContrib
Changed:
<
<
META FILEATTACHMENT attachment="json2.uncompressed.js" attr="" comment="" date="1349106887" name="json2.uncompressed.js" size="17413" user="BaseUserMapping_333" version="7"
META FILEATTACHMENT attachment="jquery.jsonrpc.uncompressed.js" attr="" comment="" date="1349106887" name="jquery.jsonrpc.uncompressed.js" size="1713" user="BaseUserMapping_333" version="7"
META FILEATTACHMENT attachment="json2.js" attr="" comment="" date="1349106887" name="json2.js" size="3377" user="BaseUserMapping_333" version="7"
META FILEATTACHMENT attachment="Makefile" attr="" comment="" date="1349106887" name="Makefile" size="136" user="BaseUserMapping_333" version="7"
META FILEATTACHMENT attachment="jquery.jsonrpc.js.gz" attr="" comment="" date="1349106887" name="jquery.jsonrpc.js.gz" size="438" user="BaseUserMapping_333" version="7"
META FILEATTACHMENT attachment="json2.js.gz" attr="" comment="" date="1349106887" name="json2.js.gz" size="1342" user="BaseUserMapping_333" version="7"
META FILEATTACHMENT attachment="jquery.jsonrpc.js" attr="" comment="" date="1349106887" name="jquery.jsonrpc.js" size="821" user="BaseUserMapping_333" version="7"
>
>
META FILEATTACHMENT attachment="json2.uncompressed.js" attr="" comment="" date="1349106887" name="json2.uncompressed.js" size="17413" user="BaseUserMapping_333" version="8"
META FILEATTACHMENT attachment="jquery.jsonrpc.uncompressed.js" attr="" comment="" date="1349106887" name="jquery.jsonrpc.uncompressed.js" size="1713" user="BaseUserMapping_333" version="8"
META FILEATTACHMENT attachment="json2.js" attr="" comment="" date="1349106887" name="json2.js" size="3377" user="BaseUserMapping_333" version="8"
META FILEATTACHMENT attachment="Makefile" attr="" comment="" date="1349106887" name="Makefile" size="136" user="BaseUserMapping_333" version="8"
META FILEATTACHMENT attachment="jquery.jsonrpc.js.gz" attr="" comment="" date="1349106887" name="jquery.jsonrpc.js.gz" size="438" user="BaseUserMapping_333" version="8"
META FILEATTACHMENT attachment="json2.js.gz" attr="" comment="" date="1349106887" name="json2.js.gz" size="1342" user="BaseUserMapping_333" version="8"
META FILEATTACHMENT attachment="jquery.jsonrpc.js" attr="" comment="" date="1349106887" name="jquery.jsonrpc.js" size="821" user="BaseUserMapping_333" version="8"
 
Revision 9
09 Oct 2012 - Main.AdminUser
 

JsonRpcContrib

%SHORTDESCRIPTION%

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

http://www.leader.it/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

<-- 
  • Set SHORTDESCRIPTION = JSON-RPC interface for Foswiki
-->

Author(s): Michael Daum
Copyright: © 2011-2012 Michael Daum http://michaeldaumconsulting.com
License: GPL (Gnu General Public License)
Release: 1.30
Version: 15467 (2012-10-01)
Change History:
<-- versions below in reverse order -->
 
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
Dependencies:
NameVersionDescription
JSON>=2.17Required. Available from the CPAN archive.
JSON::XS>=2.27Required. Available from the CPAN archive.
Home page: Foswiki:Extensions/JsonRpcContrib
Support: Foswiki:Support/JsonRpcContrib

META FILEATTACHMENT attachment="json2.uncompressed.js" attr="" comment="" date="1349106887" name="json2.uncompressed.js" size="17413" user="BaseUserMapping_333" version="7"
META FILEATTACHMENT attachment="jquery.jsonrpc.uncompressed.js" attr="" comment="" date="1349106887" name="jquery.jsonrpc.uncompressed.js" size="1713" user="BaseUserMapping_333" version="7"
META FILEATTACHMENT attachment="json2.js" attr="" comment="" date="1349106887" name="json2.js" size="3377" user="BaseUserMapping_333" version="7"
META FILEATTACHMENT attachment="Makefile" attr="" comment="" date="1349106887" name="Makefile" size="136" user="BaseUserMapping_333" version="7"
META FILEATTACHMENT attachment="jquery.jsonrpc.js.gz" attr="" comment="" date="1349106887" name="jquery.jsonrpc.js.gz" size="438" user="BaseUserMapping_333" version="7"
META FILEATTACHMENT attachment="json2.js.gz" attr="" comment="" date="1349106887" name="json2.js.gz" size="1342" user="BaseUserMapping_333" version="7"
META FILEATTACHMENT attachment="jquery.jsonrpc.js" attr="" comment="" date="1349106887" name="jquery.jsonrpc.js" size="821" user="BaseUserMapping_333" version="7"
Revision 8
09 Oct 2012 - Main.AdminUser
 

JsonRpcContrib

%SHORTDESCRIPTION%

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

http://www.leader.it/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

<-- 
  • Set SHORTDESCRIPTION = JSON-RPC interface for Foswiki
-->

Author(s): Michael Daum
Copyright: © 2011-2012 Michael Daum http://michaeldaumconsulting.com
License: GPL (Gnu General Public License)
Release: 1.30
Version: 15467 (2012-10-01)
Change History:
<-- versions below in reverse order -->
 
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
Dependencies:
NameVersionDescription
JSON>=2.17Required. Available from the CPAN archive.
JSON::XS>=2.27Required. Available from the CPAN archive.
Home page: Foswiki:Extensions/JsonRpcContrib
Support: Foswiki:Support/JsonRpcContrib
Changed:
<
<
META FILEATTACHMENT attachment="json2.uncompressed.js" attr="" comment="" date="1349106887" name="json2.uncompressed.js" size="17413" user="BaseUserMapping_333" version="6"
META FILEATTACHMENT attachment="jquery.jsonrpc.uncompressed.js" attr="" comment="" date="1349106887" name="jquery.jsonrpc.uncompressed.js" size="1713" user="BaseUserMapping_333" version="6"
META FILEATTACHMENT attachment="json2.js" attr="" comment="" date="1349106887" name="json2.js" size="3377" user="BaseUserMapping_333" version="6"
META FILEATTACHMENT attachment="Makefile" attr="" comment="" date="1349106887" name="Makefile" size="136" user="BaseUserMapping_333" version="6"
META FILEATTACHMENT attachment="jquery.jsonrpc.js.gz" attr="" comment="" date="1349106887" name="jquery.jsonrpc.js.gz" size="438" user="BaseUserMapping_333" version="6"
META FILEATTACHMENT attachment="json2.js.gz" attr="" comment="" date="1349106887" name="json2.js.gz" size="1342" user="BaseUserMapping_333" version="6"
META FILEATTACHMENT attachment="jquery.jsonrpc.js" attr="" comment="" date="1349106887" name="jquery.jsonrpc.js" size="821" user="BaseUserMapping_333" version="6"
>
>
META FILEATTACHMENT attachment="json2.uncompressed.js" attr="" comment="" date="1349106887" name="json2.uncompressed.js" size="17413" user="BaseUserMapping_333" version="7"
META FILEATTACHMENT attachment="jquery.jsonrpc.uncompressed.js" attr="" comment="" date="1349106887" name="jquery.jsonrpc.uncompressed.js" size="1713" user="BaseUserMapping_333" version="7"
META FILEATTACHMENT attachment="json2.js" attr="" comment="" date="1349106887" name="json2.js" size="3377" user="BaseUserMapping_333" version="7"
META FILEATTACHMENT attachment="Makefile" attr="" comment="" date="1349106887" name="Makefile" size="136" user="BaseUserMapping_333" version="7"
META FILEATTACHMENT attachment="jquery.jsonrpc.js.gz" attr="" comment="" date="1349106887" name="jquery.jsonrpc.js.gz" size="438" user="BaseUserMapping_333" version="7"
META FILEATTACHMENT attachment="json2.js.gz" attr="" comment="" date="1349106887" name="json2.js.gz" size="1342" user="BaseUserMapping_333" version="7"
META FILEATTACHMENT attachment="jquery.jsonrpc.js" attr="" comment="" date="1349106887" name="jquery.jsonrpc.js" size="821" user="BaseUserMapping_333" version="7"
 
Revision 7
09 Oct 2012 - Main.AdminUser
 

JsonRpcContrib

%SHORTDESCRIPTION%

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

http://www.leader.it/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

<-- 
  • Set SHORTDESCRIPTION = JSON-RPC interface for Foswiki
-->

Author(s): Michael Daum
Copyright: © 2011-2012 Michael Daum http://michaeldaumconsulting.com
License: GPL (Gnu General Public License)
Release: 1.30
Version: 15467 (2012-10-01)
Change History:
<-- versions below in reverse order -->
 
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
Dependencies:
NameVersionDescription
JSON>=2.17Required. Available from the CPAN archive.
JSON::XS>=2.27Required. Available from the CPAN archive.
Home page: Foswiki:Extensions/JsonRpcContrib
Support: Foswiki:Support/JsonRpcContrib
Changed:
<
<
META FILEATTACHMENT attachment="json2.uncompressed.js" attr="" comment="" date="1349106887" name="json2.uncompressed.js" size="17413" user="BaseUserMapping_333" version="5"
META FILEATTACHMENT attachment="jquery.jsonrpc.uncompressed.js" attr="" comment="" date="1349106887" name="jquery.jsonrpc.uncompressed.js" size="1713" user="BaseUserMapping_333" version="5"
META FILEATTACHMENT attachment="json2.js" attr="" comment="" date="1349106887" name="json2.js" size="3377" user="BaseUserMapping_333" version="5"
META FILEATTACHMENT attachment="Makefile" attr="" comment="" date="1349106887" name="Makefile" size="136" user="BaseUserMapping_333" version="5"
META FILEATTACHMENT attachment="jquery.jsonrpc.js.gz" attr="" comment="" date="1349106887" name="jquery.jsonrpc.js.gz" size="438" user="BaseUserMapping_333" version="5"
META FILEATTACHMENT attachment="json2.js.gz" attr="" comment="" date="1349106887" name="json2.js.gz" size="1342" user="BaseUserMapping_333" version="5"
META FILEATTACHMENT attachment="jquery.jsonrpc.js" attr="" comment="" date="1349106887" name="jquery.jsonrpc.js" size="821" user="BaseUserMapping_333" version="5"
>
>
META FILEATTACHMENT attachment="json2.uncompressed.js" attr="" comment="" date="1349106887" name="json2.uncompressed.js" size="17413" user="BaseUserMapping_333" version="6"
META FILEATTACHMENT attachment="jquery.jsonrpc.uncompressed.js" attr="" comment="" date="1349106887" name="jquery.jsonrpc.uncompressed.js" size="1713" user="BaseUserMapping_333" version="6"
META FILEATTACHMENT attachment="json2.js" attr="" comment="" date="1349106887" name="json2.js" size="3377" user="BaseUserMapping_333" version="6"
META FILEATTACHMENT attachment="Makefile" attr="" comment="" date="1349106887" name="Makefile" size="136" user="BaseUserMapping_333" version="6"
META FILEATTACHMENT attachment="jquery.jsonrpc.js.gz" attr="" comment="" date="1349106887" name="jquery.jsonrpc.js.gz" size="438" user="BaseUserMapping_333" version="6"
META FILEATTACHMENT attachment="json2.js.gz" attr="" comment="" date="1349106887" name="json2.js.gz" size="1342" user="BaseUserMapping_333" version="6"
META FILEATTACHMENT attachment="jquery.jsonrpc.js" attr="" comment="" date="1349106887" name="jquery.jsonrpc.js" size="821" user="BaseUserMapping_333" version="6"
 
Revision 6
09 Oct 2012 - Main.AdminUser
 

JsonRpcContrib

%SHORTDESCRIPTION%

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

http://www.leader.it/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

<-- 
  • Set SHORTDESCRIPTION = JSON-RPC interface for Foswiki
-->

Author(s): Michael Daum
Copyright: © 2011-2012 Michael Daum http://michaeldaumconsulting.com
License: GPL (Gnu General Public License)
Release: 1.30
Version: 15467 (2012-10-01)
Change History:
<-- versions below in reverse order -->
 
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
Dependencies:
NameVersionDescription
JSON>=2.17Required. Available from the CPAN archive.
JSON::XS>=2.27Required. Available from the CPAN archive.
Home page: Foswiki:Extensions/JsonRpcContrib
Support: Foswiki:Support/JsonRpcContrib

META FILEATTACHMENT attachment="json2.uncompressed.js" attr="" comment="" date="1349106887" name="json2.uncompressed.js" size="17413" user="BaseUserMapping_333" version="5"
META FILEATTACHMENT attachment="jquery.jsonrpc.uncompressed.js" attr="" comment="" date="1349106887" name="jquery.jsonrpc.uncompressed.js" size="1713" user="BaseUserMapping_333" version="5"
META FILEATTACHMENT attachment="json2.js" attr="" comment="" date="1349106887" name="json2.js" size="3377" user="BaseUserMapping_333" version="5"
META FILEATTACHMENT attachment="Makefile" attr="" comment="" date="1349106887" name="Makefile" size="136" user="BaseUserMapping_333" version="5"
META FILEATTACHMENT attachment="jquery.jsonrpc.js.gz" attr="" comment="" date="1349106887" name="jquery.jsonrpc.js.gz" size="438" user="BaseUserMapping_333" version="5"
META FILEATTACHMENT attachment="json2.js.gz" attr="" comment="" date="1349106887" name="json2.js.gz" size="1342" user="BaseUserMapping_333" version="5"
META FILEATTACHMENT attachment="jquery.jsonrpc.js" attr="" comment="" date="1349106887" name="jquery.jsonrpc.js" size="821" user="BaseUserMapping_333" version="5"
Revision 5
09 Oct 2012 - Main.AdminUser
 

JsonRpcContrib

%SHORTDESCRIPTION%

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

http://www.leader.it/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

<-- 
  • Set SHORTDESCRIPTION = JSON-RPC interface for Foswiki
-->

Author(s): Michael Daum
Copyright: © 2011-2012 Michael Daum http://michaeldaumconsulting.com
License: GPL (Gnu General Public License)
Release: 1.30
Version: 15467 (2012-10-01)
Change History:
<-- versions below in reverse order -->
 
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
Dependencies:
NameVersionDescription
JSON>=2.17Required. Available from the CPAN archive.
JSON::XS>=2.27Required. Available from the CPAN archive.
Home page: Foswiki:Extensions/JsonRpcContrib
Support: Foswiki:Support/JsonRpcContrib
Changed:
<
<
META FILEATTACHMENT attachment="json2.uncompressed.js" attr="" comment="" date="1349106887" name="json2.uncompressed.js" size="17413" user="BaseUserMapping_333" version="4"
META FILEATTACHMENT attachment="jquery.jsonrpc.uncompressed.js" attr="" comment="" date="1349106887" name="jquery.jsonrpc.uncompressed.js" size="1713" user="BaseUserMapping_333" version="4"
META FILEATTACHMENT attachment="json2.js" attr="" comment="" date="1349106887" name="json2.js" size="3377" user="BaseUserMapping_333" version="4"
META FILEATTACHMENT attachment="Makefile" attr="" comment="" date="1349106887" name="Makefile" size="136" user="BaseUserMapping_333" version="4"
META FILEATTACHMENT attachment="jquery.jsonrpc.js.gz" attr="" comment="" date="1349106887" name="jquery.jsonrpc.js.gz" size="438" user="BaseUserMapping_333" version="4"
META FILEATTACHMENT attachment="json2.js.gz" attr="" comment="" date="1349106887" name="json2.js.gz" size="1342" user="BaseUserMapping_333" version="4"
META FILEATTACHMENT attachment="jquery.jsonrpc.js" attr="" comment="" date="1349106887" name="jquery.jsonrpc.js" size="821" user="BaseUserMapping_333" version="4"
>
>
META FILEATTACHMENT attachment="json2.uncompressed.js" attr="" comment="" date="1349106887" name="json2.uncompressed.js" size="17413" user="BaseUserMapping_333" version="5"
META FILEATTACHMENT attachment="jquery.jsonrpc.uncompressed.js" attr="" comment="" date="1349106887" name="jquery.jsonrpc.uncompressed.js" size="1713" user="BaseUserMapping_333" version="5"
META FILEATTACHMENT attachment="json2.js" attr="" comment="" date="1349106887" name="json2.js" size="3377" user="BaseUserMapping_333" version="5"
META FILEATTACHMENT attachment="Makefile" attr="" comment="" date="1349106887" name="Makefile" size="136" user="BaseUserMapping_333" version="5"
META FILEATTACHMENT attachment="jquery.jsonrpc.js.gz" attr="" comment="" date="1349106887" name="jquery.jsonrpc.js.gz" size="438" user="BaseUserMapping_333" version="5"
META FILEATTACHMENT attachment="json2.js.gz" attr="" comment="" date="1349106887" name="json2.js.gz" size="1342" user="BaseUserMapping_333" version="5"
META FILEATTACHMENT attachment="jquery.jsonrpc.js" attr="" comment="" date="1349106887" name="jquery.jsonrpc.js" size="821" user="BaseUserMapping_333" version="5"
 
Revision 4
09 Oct 2012 - Main.AdminUser
 

JsonRpcContrib

%SHORTDESCRIPTION%

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

http://www.leader.it/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

<-- 
  • Set SHORTDESCRIPTION = JSON-RPC interface for Foswiki
-->

Author(s): Michael Daum
Copyright: © 2011-2012 Michael Daum http://michaeldaumconsulting.com
License: GPL (Gnu General Public License)
Release: 1.30
Version: 15467 (2012-10-01)
Change History:
<-- versions below in reverse order -->
 
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
Dependencies:
NameVersionDescription
JSON>=2.17Required. Available from the CPAN archive.
JSON::XS>=2.27Required. Available from the CPAN archive.
Home page: Foswiki:Extensions/JsonRpcContrib
Support: Foswiki:Support/JsonRpcContrib
Changed:
<
<
META FILEATTACHMENT attachment="json2.uncompressed.js" attr="" comment="" date="1349106887" name="json2.uncompressed.js" size="17413" user="BaseUserMapping_333" version="3"
META FILEATTACHMENT attachment="jquery.jsonrpc.uncompressed.js" attr="" comment="" date="1349106887" name="jquery.jsonrpc.uncompressed.js" size="1713" user="BaseUserMapping_333" version="3"
META FILEATTACHMENT attachment="json2.js" attr="" comment="" date="1349106887" name="json2.js" size="3377" user="BaseUserMapping_333" version="3"
META FILEATTACHMENT attachment="Makefile" attr="" comment="" date="1349106887" name="Makefile" size="136" user="BaseUserMapping_333" version="3"
META FILEATTACHMENT attachment="jquery.jsonrpc.js.gz" attr="" comment="" date="1349106887" name="jquery.jsonrpc.js.gz" size="438" user="BaseUserMapping_333" version="3"
META FILEATTACHMENT attachment="json2.js.gz" attr="" comment="" date="1349106887" name="json2.js.gz" size="1342" user="BaseUserMapping_333" version="3"
META FILEATTACHMENT attachment="jquery.jsonrpc.js" attr="" comment="" date="1349106887" name="jquery.jsonrpc.js" size="821" user="BaseUserMapping_333" version="3"
>
>
META FILEATTACHMENT attachment="json2.uncompressed.js" attr="" comment="" date="1349106887" name="json2.uncompressed.js" size="17413" user="BaseUserMapping_333" version="4"
META FILEATTACHMENT attachment="jquery.jsonrpc.uncompressed.js" attr="" comment="" date="1349106887" name="jquery.jsonrpc.uncompressed.js" size="1713" user="BaseUserMapping_333" version="4"
META FILEATTACHMENT attachment="json2.js" attr="" comment="" date="1349106887" name="json2.js" size="3377" user="BaseUserMapping_333" version="4"
META FILEATTACHMENT attachment="Makefile" attr="" comment="" date="1349106887" name="Makefile" size="136" user="BaseUserMapping_333" version="4"
META FILEATTACHMENT attachment="jquery.jsonrpc.js.gz" attr="" comment="" date="1349106887" name="jquery.jsonrpc.js.gz" size="438" user="BaseUserMapping_333" version="4"
META FILEATTACHMENT attachment="json2.js.gz" attr="" comment="" date="1349106887" name="json2.js.gz" size="1342" user="BaseUserMapping_333" version="4"
META FILEATTACHMENT attachment="jquery.jsonrpc.js" attr="" comment="" date="1349106887" name="jquery.jsonrpc.js" size="821" user="BaseUserMapping_333" version="4"
 
Revision 3
09 Oct 2012 - Main.AdminUser
 

JsonRpcContrib

%SHORTDESCRIPTION%

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

http://www.leader.it/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

<-- 
  • Set SHORTDESCRIPTION = JSON-RPC interface for Foswiki
-->

Author(s): Michael Daum
Copyright: © 2011-2012 Michael Daum http://michaeldaumconsulting.com
License: GPL (Gnu General Public License)
Release: 1.30
Version: 15467 (2012-10-01)
Change History:
<-- versions below in reverse order -->
 
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
Dependencies:
NameVersionDescription
JSON>=2.17Required. Available from the CPAN archive.
JSON::XS>=2.27Required. Available from the CPAN archive.
Home page: Foswiki:Extensions/JsonRpcContrib
Support: Foswiki:Support/JsonRpcContrib
Changed:
<
<
META FILEATTACHMENT attachment="json2.uncompressed.js" attr="" comment="" date="1349106887" name="json2.uncompressed.js" size="17413" user="BaseUserMapping_333" version="2"
META FILEATTACHMENT attachment="jquery.jsonrpc.uncompressed.js" attr="" comment="" date="1349106887" name="jquery.jsonrpc.uncompressed.js" size="1713" user="BaseUserMapping_333" version="2"
META FILEATTACHMENT attachment="json2.js" attr="" comment="" date="1349106887" name="json2.js" size="3377" user="BaseUserMapping_333" version="2"
META FILEATTACHMENT attachment="Makefile" attr="" comment="" date="1349106887" name="Makefile" size="136" user="BaseUserMapping_333" version="2"
META FILEATTACHMENT attachment="jquery.jsonrpc.js.gz" attr="" comment="" date="1349106887" name="jquery.jsonrpc.js.gz" size="438" user="BaseUserMapping_333" version="2"
META FILEATTACHMENT attachment="json2.js.gz" attr="" comment="" date="1349106887" name="json2.js.gz" size="1342" user="BaseUserMapping_333" version="2"
META FILEATTACHMENT attachment="jquery.jsonrpc.js" attr="" comment="" date="1349106887" name="jquery.jsonrpc.js" size="821" user="BaseUserMapping_333" version="2"
>
>
META FILEATTACHMENT attachment="json2.uncompressed.js" attr="" comment="" date="1349106887" name="json2.uncompressed.js" size="17413" user="BaseUserMapping_333" version="3"
META FILEATTACHMENT attachment="jquery.jsonrpc.uncompressed.js" attr="" comment="" date="1349106887" name="jquery.jsonrpc.uncompressed.js" size="1713" user="BaseUserMapping_333" version="3"
META FILEATTACHMENT attachment="json2.js" attr="" comment="" date="1349106887" name="json2.js" size="3377" user="BaseUserMapping_333" version="3"
META FILEATTACHMENT attachment="Makefile" attr="" comment="" date="1349106887" name="Makefile" size="136" user="BaseUserMapping_333" version="3"
META FILEATTACHMENT attachment="jquery.jsonrpc.js.gz" attr="" comment="" date="1349106887" name="jquery.jsonrpc.js.gz" size="438" user="BaseUserMapping_333" version="3"
META FILEATTACHMENT attachment="json2.js.gz" attr="" comment="" date="1349106887" name="json2.js.gz" size="1342" user="BaseUserMapping_333" version="3"
META FILEATTACHMENT attachment="jquery.jsonrpc.js" attr="" comment="" date="1349106887" name="jquery.jsonrpc.js" size="821" user="BaseUserMapping_333" version="3"
 
Revision 2
09 Oct 2012 - Main.AdminUser
Deleted:
<
<
 

JsonRpcContrib

%SHORTDESCRIPTION%

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

http://www.leader.it/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

<-- 
  • Set SHORTDESCRIPTION = JSON-RPC interface for Foswiki
-->

Author(s): Michael Daum
Copyright: © 2011-2012 Michael Daum http://michaeldaumconsulting.com
License: GPL (Gnu General Public License)
Changed:
<
<
Release: 1.22
Version: 15254 (2012-08-02)
>
>
Release: 1.30
Version: 15467 (2012-10-01)
 
Change History:
<-- versions below in reverse order -->
 
Added:
>
>
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
Dependencies:
NameVersionDescription
JSON>=2.17Required. Available from the CPAN archive.
JSON::XS>=2.27Required. Available from the CPAN archive.
Home page: Foswiki:Extensions/JsonRpcContrib
Support: Foswiki:Support/JsonRpcContrib
Added:
>
>

META FILEATTACHMENT attachment="json2.uncompressed.js" attr="" comment="" date="1349106887" name="json2.uncompressed.js" size="17413" user="BaseUserMapping_333" version="2"
META FILEATTACHMENT attachment="jquery.jsonrpc.uncompressed.js" attr="" comment="" date="1349106887" name="jquery.jsonrpc.uncompressed.js" size="1713" user="BaseUserMapping_333" version="2"
META FILEATTACHMENT attachment="json2.js" attr="" comment="" date="1349106887" name="json2.js" size="3377" user="BaseUserMapping_333" version="2"
META FILEATTACHMENT attachment="Makefile" attr="" comment="" date="1349106887" name="Makefile" size="136" user="BaseUserMapping_333" version="2"
META FILEATTACHMENT attachment="jquery.jsonrpc.js.gz" attr="" comment="" date="1349106887" name="jquery.jsonrpc.js.gz" size="438" user="BaseUserMapping_333" version="2"
META FILEATTACHMENT attachment="json2.js.gz" attr="" comment="" date="1349106887" name="json2.js.gz" size="1342" user="BaseUserMapping_333" version="2"
META FILEATTACHMENT attachment="jquery.jsonrpc.js" attr="" comment="" date="1349106887" name="jquery.jsonrpc.js" size="821" user="BaseUserMapping_333" version="2"
 
 
This site is powered by FoswikiCopyright © by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Ideas, requests, problems regarding Foswiki? Send feedback Privacy policy & use of cookies