FLOW3 and JSON-RPC, a happy couple?

9 July 2012 Comments Off

A highly AJAX-ified web application tends to get more difficult to maintain as it grows, both on client and server side. If in the JavaScript part of the application one can use libraries that simplify use of XMLHTTP requests, on the server side things go not so well. On a MVC framework each request gets served by a controller action, practically a method of a controller object. So, in the case of a large, AJAX-ified web application you’ll find yourself writing tens of controller methods to serve AJAX requests, a lot of them being little CRUD operations.

Analyzing AJAX requests that come to the server-side of a web application we could identify the following types:

· CRUD (Create, Read, Update, Delete) operations (e.g. create a comment, read a news counter, update votes count on an item, delete a comment). These requests usually expect scalar values or confirmation messages. These operations are sometimes designed in a RESTful manner, leveraging the architectural style of HTTP.

· Partial page content (partial refresh) requests. These are those requests for HTML code to insert in some container element in the DOM. These requests are usually served by directly rendering a partial view and outputting contents. This approach has the disadvantage that any exceptions thrown while serving the request end up displayed in the page, if not handled properly on the server and in the client code.

In a RESTful approach the error state of the request is returned by the HTTP status code . Status codes can also be used in refeshing partial page content (the 4xx codes). But status codes were not meant for expressing application specific errors, moreover HTTP status codes are reserved by software vendors for specific use and basing an application error handling mechanism on a volatile set of unused status codes is not desirable.

To enable properly error handling we often use a JSON response of the form { “success” : true|false, “message”: “…” , html: “…..” } for AJAX requests that request HTML content and something similar for CRUD operation requests. This way error situations are made known to the client-side script and suitable decisions can be made, like displaying the error message in a dialog. We consider this a step further in creating a transparent interface between the client-side and the server-side, but there is place for better.

JSON-RPC  standard seems to be a candidate for a better standard in AJAX communication. JSON-RPC is a RPC protocol that uses JSON-encoded messages . It is “a stateless, light-weight remote procedure call (RPC) protocol. Primarily this specification defines several data structures and the rules around their processing” , as its proposers say. Some of the obvious advantages of using JSON-RPC are:

  • · simple standard, has been around for some time now, so almost everybody has heard of it
  • · application specific error handling (code, message and data)
  • · it permits request batches (sending a batch of operations at a time can reduce the number of simultaneous AJAX requests).
  • Now that we set on using JSON-RPC, we wanted to be able to use its advantages in a FLOW3 web application. For this purpose we created a package that can be used to provide JSON-RPC operation calls for any number of exposed service providing classes, for any of the application’s packages. The package consists of our own JSON-RPC implementation in PHP and it is capable of exposing service classes methods through a single controller action method. The actual class serving the requests (serviceProvider) is specified in the FLOW3 routes config file.

    Here is an example of configuring such a route (from Routes.yaml):

    name: ‘Arithmetic service’

    uriPattern: ‘arithmetic’


    ‘@package’: ‘Arxia.Rpc’

    ‘@controller’: ‘JsonRpc’

    # the action that serves JSON-RPC requests

    ‘@action’: ‘serve’

    # the format of the response is json

    ‘@format’: ‘json’

    # service provider is the class whose methods are exposed, here arithmetic operations

    ‘serviceProvider’: ‘\Arxia\Calculator\Service\Arithmetic’

    It is important to note that one can have as many service providers as one wants in his applications, even in different packages and expose them using the Arxia.Rpc package’s JsonRpcController class. So installing the generic Arxia.Rpc package one has JSON-RPC support for any other package, by defining a route for each of the uses.

    Looking at the integration example briefly described above we saw that FLOW3 and JSON-RPC really make a happy couple and we believe that embracing JSON-RPC as the standard of making AJAX requests throughout a dynamic, greatly AJAX-ified web application provides a better application structure, better error handling, better understanding of existing code and application flow, better team members communication and, as a result of all these, better productivity. Sure there are other approaches with their pros and cons, but the aforementioned advantages makes JSON-RPC a candidate in a large application in the future, as the standard of AJAX communication.

    Sources can be downloaded from here

    Author: Dan Homorodean