Skip to content

HTTPS clone URL

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.
LICENSE
README.md

README.md

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

Additions

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.

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" }
                }
            }
        }
    }
}
Something went wrong with that request. Please try again.