“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.