Introduction

radial is a project to provide a polyglot "api first" platform for projects on Heroku.

The goal of the project is to enable you to write services/API's in the language of your choice, allowing you and your team to use the best tool for the job based around your skillset.

radial consists of a proxy server, the radial engine, built in node.js that sits in front of various service handlers.

Service handlers are all written in a style inspired by json-rpc with some changes to better suit the design of radial. Service handlers can be written in any language as long as they follow the radial request/response pattern.

Service Handlers

Service handlers work in a request/response pattern.

Request Object

A request is defined as a JSON object consisting of a method string and a params object.

{
    method: "service_name.method_name",
    params: {
        param1: "some info",
        param2: "more info",
        param3: "and so on"
    }
}

"service_name" is the name that the service object is registered as

"method_name" is the name of the method being called on that service.

For example you could have the FooService service handler mapped to "fooService" and it could have a method named blah, so the method string would in that case be "fooService.blah". You are free to use whatever naming scheme you desire in mapping your service objects.

Response Object

A response object is defined as a JSON object consisting of a result object and an error object. If result is set then error must be null and vice-versa.

{
    result: {
        success: "true"
    },
    error: null
}

The service handler response class defines getters and setters for both result and error and has a custom toJSON object to allow for serialization of the result and error variables.

Mapping Services

Services are mapped for now via a simple JSON file. There is a default route that acts as a catchall. Any other routes override the default.

{
    "services" : [
        {
            "host": "localhost",
            "port": 3000,
            "path": "/api",
            "default": true,
            "services": null
        },
        {
            "host": "localhost",
            "port": 3001,
            "path": "/api",
            "services": [ "security", "help", "sleep" ]
        },
        {
            "host": "localhost",
            port": 3000,
            path": "/api",
            services": [ "help" ]
        }
    ]
}

In the example above there is a default service handler at localhost:3000/api. It will catch all requests that don't have a service endpoint defined by one of the other routes. The localhost:3001/api route will pick up any requests for the security, help, or sleep services. The localhost:3000/api will also pick up the help service and since there is already a service endpoint for that service, the radial engine will do a simple random load balance between the two endpoints for requests to the help service.

Service handler endpoints can be any URL as long as it points to a radial service handler on Heroku.

For security purposes in production mode radial proxy will only work over HTTPS.