YAML-RPC README

Ilya V. Portnov portnov84@rambler.ru

The yaml-rpc package contains a small library to organize remote procedure call (RPC) over TCP/IP network, using JSON as data serialization format.

RPC server should supply a set of "RPC methods", which are simply functions :: a -> b -> ... -> IO c. Arguments must be of class ToJSON (defined in aeson package); result must be of class FromJSON (defined in aeson package too). One can of cause use GHC Generics mechanism to derive needed instances. yaml-rpc package provides a (TemplateHaskell) function Network.YAML.TH.Server.makeAPI to generate API description for server. Such API can be automatically written to file in simple YAML format by using function Network.YAML.TH.Server.writeAPI. It is possible to write different servers, which will use generated API description and provide HTTP REST JSON services with that API. Currently there is only one implementation using scotty package; it is provided by yaml-rpc-scotty package. Please see yaml-rpc-scotty/Test/{Server.hs, TestAPIImpl.hs} files for example usage.

RPC client calls that functions via HTTP REST JSON interface. So, it can be used either from Haskell or from any other environment. For example, it can be easily used from JavaScript with JQuery or another framework. For Haskell, yaml-rpc package provides a function Network.YAML.Caller.call to call any method via HTTP REST JSON interface. Moreover, a (TemplateHaskell) function Network.YAML.TH.Client.useAPI function will read API description from file (in YAML format) and generate wrapper methods for calling respective remote methods. Please see Test/Client.hs for example usage.

Currently, only one-connection-per-call mode is supported by Caller module. There are plans to implement persistent connection support.

API description files can contain not only methods description, but also data types description. Types description can be also automagically generated from usual Haskell definitions and written to API description file. Then, when reading that API description file, usual Haskell data type definitions are generated.

Please see test.api file for example of API description format.

On the server side, usual workflow is as following:

• Write some number of API data types and functions to be exposed.
• Call makeAPI function to generate API description.
• Call writeAPI function to write API description to file.
• Call generateDispatcher function on generated API to generate function dispatch :: Text -> Maybe (Value -> IO Value). This function will be used by any server implementation.
• Launch any server implementation and provide it by dispatch function.

On the client side, usual workflow is as following:

• Receive API description file from service provider.
• Call useAPI function on that file; it will generate data types definitions and wrapper functions to call all methods declared in file.
• Call generated wrappers.

Depends: ghc >= 7.6, yaml, template-haskell, th-lift, wreq, lens, scotty.