Skip to content


Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
branch: master

Fetching latest commit…

Cannot retrieve the latest commit at this time

Failed to load latest commit information.

LinguaLeo RPC protocol specification


Request should be encoded using json. Format described below:

    "id" : "10",
    "v" : "1",
    "method" : "methodName",
    "args": ["array", "of", "args"],
    "reply" : true
Parameter Format Description Default
id Any number Unique client identifier (big random)
v Any number Version of the method 1
method String in camelCase Method name to be called on server
args Associative array, all keys names must be in camelCase Arguments will be passed into server's method (Empty array)
reply Boolean Does a request require a reply true


Response should be encoded using json too. Format described below:

    "reply" : ["some result"],
    "code" : 1,
    "error": "error occurred"
Parameter Format Description Default
reply Associative array, all keys names must be in camelCase Reply data (Empty array)
code Number Error code 0
error String Error message (Empty string)

If no error occurred error code must be set to 0 and error message to empty string.

There is common errors codes:

  • 1 - Method not found
  • 2 - Version not supported

Redis implementation details

Implementation uses Redis lists to organize queues.

Client flow:

  • Client forms request
  • Client pushes encoded request (using LPUSH) to Redis list, key format must be server.[endpoint]
  • If reply is needed then client waits (using BRPOP) until key with name client.[client id] is appeared

Server flow:

  • Server gets the encoded request from list (using BRPOP). List key format is server.[endpoint]
  • Server processes the request
  • If reply is needed then server pushes (using LPUSH) message to list. List key name must be client.[client id]
  • The server should set expiration on the client key for 10 seconds


If the reply is needed, then .reply can be added as suffix to [endpoint] (email => email.reply). In this case you should run server on both endpoints: email and email.reply.

Service definition

The service should implement special methods.


The command returns the service definition (description, methods).


  • version: 1
  • method: discover
  • args: ['methodName1', 'methodNameN'], optional


    "v": 1,
    "method": "discover"


The reply has two properties on the root:

  • service - description of the service, optional
  • methods - list of existed methods

A method is described by three properties:

  • description - description of the method, optional
  • parameters - existed parameters (for more information see Example), optional
  • returns - result data type, optional

A parameter is described by two properties:

  • type - data type (available types: string, integer, float, boolean, array, _schema_, default string)
  • default - default value, optional


    "reply": {
        "service": "Calculator",
        "methods": {
            "add": {
                "parameters": [  // an array indicates positional parameters
                    { "type": "integer", "default": 0 },
                    { "type": "integer", "default": 0 }
                "returns": "integer"
            "divide": {
                "description": "Do division",
                "parameters": {
                    "divisor": { "type": "integer" },
                    "dividend": { "type": "integer" }
                "returns": "float"
            "doNothing": {}, // no requirements on parameters or return type
            "getAddress" : {
                "description": "Takes a person and returns an address",
                "parameters": {
                    "person": {
                         // for the type we use a schema
                        "type": { 
                            "firstName": { "type": "string" }, 
                            "lastName": { "type": "string" } 
                // use a schema for the return type
                "returns": {
                    "street": { "type": "string" },
                    "zip": { "type": "string" }, 
                    "state": { "type": "string" },
                    "town": { "type": "string" }
Something went wrong with that request. Please try again.