Main  /  Edit  /  History  /   /  Users Area



JSON-RPC is remote procedure call protocol implemented using JSON data.

It is a lightweight protocol that allows easy Ajax based communication between the browser and the C++ application.

CppCMS implements JSON-RPC 1.0 specifications over HTTP protocol.

JSON-RPC Service


Let's create a simple RPC service that allows us to add and divide numbers.

JSON-RPC Service should be derived from cppcms::rpc::json_rpc_server that on the other hand is derived from cppcms::application.

class json_service : 
    public cppcms::rpc::json_rpc_server {

When we use JSON-RPC service we bind between PRC methods and the application member functions, similarly to what we done for URL dispatching.

In our case:

json_service(cppcms::service &srv) : cppcms::rpc::json_rpc_server(srv)


Similarly to URL mapper we connect the "sum" member function to "sum" JSON-RPC method and specify that this is a method that should return a value (not notification)

Now we implement our service:

void sum(int x,int y)
void div(int x,int y)
        return_error("Division by zero");

Please note, out functions create two types of the response: normal result response and error response as defined by JSON-RPC specification.

The parameters of the method call are automatically converted to appropriate C++ object. If the conversion can't be done, the error would be automatically returned and the functions would not be called. Similarly integer result is automatically converted to cppcms::json::value

Similarly to the way we mount cppcms::application based classes we create our JSON-RPC service:

cppcms::service srv(argc,argv);
srv.applications_pool().mount( cppcms::applications_factory<json_service>());;

Client Side Code

Let's create a small form that would handle RPC request for us:

<form onsubmit="return call();">
    <input type="text" id="x" />
    <input type="submit" value="/" />
    <input type="text" id="y" /> =
    <span id="result"></span>

Now let's implement JSON-RPC call using XmlHTTPRequest - function call:

function call() {

First we create the XMLHttpRequest object and set essential content-type "application/json":

var xhr = new XMLHttpRequest();"post", '/rpc');
// Required by JSON-RPC over HTTP

Then we configure our JSON-RPC request:

// It is better to use real formatter like JSON.js
var x=parseInt(document.getElementById('x').value);
var y=parseInt(document.getElementById('y').value);
var request = '{"method":"div","params":[' + x + ',' + y +'],"id":1}';

Define onreadystatechange callback and send the request:

xhr.onreadystatechange = function() {
return false;

The callback function would look like:

if (xhr.readyState === 4) {
    var res;
    if(xhr.status === 200) {
        // Don't call eval in real code use some parser
        var result = eval('(' + xhr.responseText + ')');
        if(result.error==null) {
            res = result.result;
        else {
            res = result.error;
    else {
        res = 'Invalid Status ' + xhr.status;
    document.getElementById('result').innerHTML = res;

Upon successful completion of XHR we parse the response and setup the result value.


JSON-RPC specifies two types of remote calls:

The two functions above (div and sum) were methods. If we want to have notifications we can create them as simple as methods:


Notification method notify function should not call return_result or return_error, on the other hand both should return the result if required:

void notify(std::string msg)
    std::cout << "We got notification " << msg << std::endl;
void both(std::string msg)
        std::cout << "We got notification " << msg << std::endl;

JSON-PRC Clients

There are many client side toolkits like Dojo that provide sophisticated JSON-RPC clients. Feel free to choose whatever client you like as long as it supports JSON-RPC 1.0.

Note: JSON-RPC 1.0 is the only valid standard, JSON-RPC 2.0 is still draft and relays on JSON-Schema that is draft-standard as well, that is why it is not implemented.

You can also find a simple JSON-RPC client in CppCMS sources under contrib/client_side/jsonrpc

JSON | Top | Internationalization and Localization


CppCMS is a web development framework for performance demanding applications.

Support This Project Logo

Поддержать проект

CppCMS needs You


Main Page

Valid CSS | Valid XHTML 1.0