RFC4627 (JSON) and JSON-RPC for Erlang

Version: HEAD

Authors: Tony Garnock-Jones (tonyg@lshift.net), LShift Ltd. (query@lshift.net).

References

RFC 4627, the JSON RFC
The JSON-RPC specification 1.1 working draft (mirrored locally).

An implementation of JSON and JSON-RPC for Erlang.

See rfc4627, the JSON/RFC4627 codec itself, to learn how to encode and decode JSON objects from Erlang code.

Providing and calling JSON-RPC services

See rfc4627_jsonrpc, a JSON-RPC service registry and transport-neutral service method invocation mechanism, to learn how to expose Erlang processes as remotely-callable JSON-RPC services, and to learn how to invoke local JSON-RPC services from Erlang without the overhead of HTTP.

Exposing JSON-RPC services over HTTP

Using Inets

See rfc4627_jsonrpc_inets, an Inets HTTP transport binding for JSON-RPC, to learn how to configure the Inets HTTP server to respond to JSON-RPC requests.

Using Mochiweb

See rfc4627_jsonrpc_mochiweb to learn how to delegate incoming Mochiweb HTTP requests to the JSON-RPC service dispatcher.

Using Cowboy

See rfc4627_jsonrpc_cowboy to learn how to delegate incoming Cowboy HTTP requests to the JSON-RPC service dispatcher.

Running the example test service that comes with the source code

Included with the Erlang RFC4627 source code is a small Inets-based example that defines a "hello world"-style JSON-RPC service, and calls it from a Javascript program embedded in a web page.

At your Erlang shell,

after compiling the code with "make all test-compile",
when your current working directory contains the "test" directory from the distribution, such that "test/server_root/conf/httpd.conf" exists,

type test_jsonrpc_inets:start_httpd(). This will

start the inets httpd on port 5671 (from test/server_root/conf/httpd.conf)
allow HTTP access to JSON-RPC services via a url prefix of "/rpc" (again from httpd.conf)
start the rfc4627_jsonrpc service registry
register the test service

Visiting http://localhost:5671/ in your browser should load a page that uses javascript to invoke the Erlang-implemented JSON-RPC test service.

Invoking JSON-RPC procedures from Javascript

Once rfc4627_jsonrpc_inets is configured as part of a running inets httpd, services can be accessed via HTTP POST and (conditionally) HTTP GET. This distribution includes Javascript code for invoking JSON-RPC services from within a web browser:

json.js: a slightly modified version of the original json.org Javascript JSON codec
jsonrpc.js: classes for XmlHttpRequest-based JSON-RPC service access
prototype-1.4.0.js: provides cross-browser XmlHttpRequest implementation, as well as many very useful utilities and a framework for class-based programming in Javascript
test-client.js: running-example javascript client code
index.html: loads and runs the running-example client

The main class for JSON-RPC service access is jsonrpc.js's JsonRpcService class.

var serviceName = "test"; // or whatever your service is registered as
var locationBase = document.location; // e.g. "http://localhost:5671/"
var jsonRpcPrefix = "rpc/"; // or as configured in your httpd.conf

var testService = new JsonRpcService(locationBase + jsonRpcPrefix + serviceName, onReady);

function onReady() {
    // callback invoked when the service is opened and ready for requests
    testService.test_proc("Hello, world!").addCallback(process_reply);
    function process_reply(reply) {
        // ...
    }
}

When an instance of JsonRpcService is constructed, it immediately calls the system.describe method of the service. When the result arrives, it uses the service description to add methods for each available service procedure to itself (see installGenericProxy in jsonrpc.js), and then calls the onReady callback supplied to the constructor to indicate that it is ready to process requests.

Javascript's network primitives force you to work in continuation-passing-style. Every service procedure available on a JsonRpcService instance is asynchronous: calling one returns an instance of JsonRpcTransaction. The addCallback method of JsonRpcTransaction can be used to add a handler for processing the result of a JSON-RPC service request. The addErrorCallback is used to catch notifications of error responses to a JSON-RPC service request.

myService.myServiceProcedure(arg).addCallback(myReplyHandler).addErrorCallback(myErrorHandler);

(note that addCallback and addErrorCallback return the JsonRpcTransaction object for convenience, to allow chaining as seen above.)

Generated by EDoc, Nov 21 2012, 14:49:55.