json_rpc is a complete implementation of the JSON-RPC 1.1 protocol, as described in the JSON-RPC 1.1 Specification draft, which may be found at http://json-rpc.org/wd/JSON-RPC-1-1-WD-20060807.html.

JSON-RPC 1.1 is a fast and lightweight text-based protocol based on HTTP. The plugin automatically chooses between GET and POST requests based on the idempotency of the remote procedures using the introspective features of JSON-RPC 1.1.

The json_rpc plgin allows a Rails application to choose to act as a service provider, as a client, or both. The plugin allows an application to set up an unlimited number of API services.

More information on

        http://rubyforge.org/projects/json-rpc/

Documentation:

        http://json-rpc.rubyforge.org/

Installation:

        script/plugin install svn://rubyforge.org/var/svn/json-rpc

An example

Server side

A Rails app may host any number of services. A service is declared in a controller, e.g.:

  class ExampleServiceController < ApplicationController

    json_rpc_service :name => 'DemoService',                     # required
         :id => 'urn:uuid:fdba4820-276b-11dc-ab85-0002a5d5c51b', # required
         :version => '0.1',                                      # optional
         :summary => 'A simple demonstration service.',          # optional
         :help => 'http://127.0.0.1:3000/services/index.html',   # optional
         :address => 'http://127.0.0.1:3000/services'            # optional

    json_rpc_procedure :name => 'sum', :proc => :+,            # required
         :summary => 'Sums two numbers.',                      # optional
         :help => 'http://127.0.0.1:3000/services/sum.html',   # optional
         :idempotent => true,                                  # optional
         :params => [{:name => 'a', :type => 'num'},           # optional
                     {:name => 'b', :type => 'num'}],          # optional
         :return => {:type => 'num'}                           # optional

    json_rpc_procedure :name => 'time', :proc => lambda { Time.now.to_s }

  end

This defines a service called "DemoService", a purely descriptive name, and two remotely callable procedures called "sum" and "time". "sum" takes two numerical arguments and returns a number. "time" takes no arguments and may return anything. "sum" is declared to be idempotent; "time" is not.

Create a controller for each JSON-RPC service you need. Then declare routes for them in Rails’ config/routes.rb file:

  ActionController::Routing::Routes.draw do |map|
    map.connect 'services/*method', :controller => 'example_service',
                :action => 'receive_json_rpc_request'
  end

"services" is the external name of the service (it can be anything, of course). The complete URI to your service will be something like http://www.yoursite.com/services.

Client Side

To connect to a service as defined above (locally or remotely), simply evaluate

        s = JsonRpcClient.new 'http://www.yoursite.com/services'

You can now call procedures remotely using s as the receiving object:

        s.time
        s.sum 24, 6
        s.sum :a => 24, :b => 6
        s.sum :b => 6, :a => 24
        s.sum :b => 6, '0' => 24
        s.sum '0' => 24, '1' => 6

Note that all the above calls to sum are equivalent. For further information, see the JSON-RPC 1.1 specification draft. The use of named arguments is encouraged.