How to use

The API of this plugin has changed a lot since the initial release. The original idea was to simplfy JSON-RPC calls so they can be used almost like a plain function call. The JSON-RPC setup has two parts: configuration and call. Configuration may look like this:

var myRpcCaller = new JSONRPC({
    url: '/serivces/jsonrpc',
    methodname: 'mymethod',
    onSuccess: function(response){
        console.log(response)
    }
});

The above code creates a myRpcCaller object, that is bound to remote mymethod method. This binding allows us to call the remote method passing only parameters and callbacks, without repeating the method multiple times:

myRpcCaller.send({params: "some text", onSuccess: function(){
    console.log('we did it!');
    }
});

Options

Options for JSON-RPC configuration are as follows:

• url: String The URL of the JSON-RPC service. Defaults to '/'.
• methodname: String Name of the remote method. Defaults to null. This option is not required. It can be specified later when using the send function.
• params: Array or Object Either a list of parameters, or an object containing the parameters that will be passed to the remote method. Defaults to null. This option is not required.
• method: String HTTP method to use in the request. This is passed directly to Request.JSON.
• encoding: String Encoding scheme. It is passed through to Request.JSON.
• headers: String Request headers. Passed through to Request.JSON.

Callback methods

The JSONRPC class has four events and you can specify the matching callbacks.

• success / onSuccess: This event is fired when the JSON-RPC call is finished, and the id returned from the server matches the one used in the request.
• failure / onFailure: This event is fired when the HTTP request fails. This even does not signify that the actual RPC call failed. For the RPC failure (soft failure) use the idMismatch and remoteFailure methods.
• remoteFailure / onRemoteFailure: This event is fired when the remote method raises an exception. You should use this method in order to handle remote exceptions. Only the error key of the complete response is returned.
• idMismatch / onIdMismatch: This event is fired when the RPC id returned by the server does not match the one sent by JSONRPC call. Although the complete response object is passed to the callback function, it would probably be unwise to treat it as safe.

Sending requests

You send JSON-RPC requests using the send function. This function takes a single object as is argument. If any of the object properties matches the one specified in the configuration, it will override the configuration. The object can have the following properties:

• method: String The remote method name.
• params: Array or Object Parameters to pass to remote method.
• id: The RPC call id.
• onSuccess, onFailure, onRemoteFailure, onIdMismatch: Function Callback methods. These will override the configured methods. Note that specifying callback methods when calling send will not only override the configured callbacks, but also prevent the events from being fired, so anything listening to the events will not be able to catch them.

Acknowledgements

I thank the following people for their invaluable advice, code, and generally being cool guys to talk to (in no particular order).

• Arian Stolwijk (arian)
• Mark Obcena (keeto)
• [Adrian Statescu](Adrian Statescu) (thinkphp)

Bugs And Feature Requests

Report any issues to the github issue tracker.

Known Issues

Params and Original JSON-RPC 1.0

The first version of the specification requires that the parameters are specified inside an array. JSONRPC plugin doesn't check for this, so it is your job to ensure this. Later version of the specification also allow objects to be used in place of arrays, which makes it possible to use named parameters.

Discuss

A note on comments here: These comments are moderated. No comments will show up until they are approved. Comments that are not productive (i.e. inflammatory, rude, etc) will not be approved.

Found a bug in this plugin? Please report it this repository's Github Issues.