LinguaLeo RPC protocol specification

Request

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

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

Service definition

The service should implement special methods.

discover

---

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

Request

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

Example:

{
    "v": 1,
    "method": "discover"
}

Response

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

Example:

{
    "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" }
                }
            }
        }
    }
}