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.