The Imagine REST API

The ImagineREST API provides the software, data, and services of Imagine's risk and portfolio management computational engine via the internet's predominant web service design model, REST. The REST API allows you to easily and transparently send requests to a cluster (farm) of one or more computational engines called compute servers. The compute server is the heart of Imagine's risk and portfolio management service.

The REST API leverages the Imagine Financial Platform (IFP) and its JavaScript execution environment and allows clients to expose IFP Apps, written in JavaScript, via a RESTful web service interface. The REST API and its interface provide a unified, scalable, modern, standards-compliant interface to Imagine's platform offering.

Using the Web Service Interface

The Imagine REST API presents a simple RESTful web service interface. Users specify request and response messages in JSON (JavaScript Object Notation). Requests are dispatched based on their URIs.

You can interact with the Imagine REST API with a simple command line tool or using modern programming languages and tools.

Quick Start

To access the REST API, use https://api.derivatives.com/farm.

The examples available here assume the use of the tool cURL. User-supplied input is shown within angle brackets, i.e., < and >.

Authentication

The REST API uses basic authentication over HTTPS. Users must provide an authorization token with every request.

REST Resources for the Imagine REST API

A small set of resources are the gateway to a large set of features:

Start a node: POST cluster
List available nodes: GET cluster
Stop a node: POST cluster/<id>/stop
Stop a node: DELETE cluster/<id>
Invoke an IFP app: GET app/<appName>/<exportedFunction>

Starting a Node

POST cluster

Starts a compute server and returns a JSON object with its id, name, and group.

Parameters
name	Optional. Defaults to id.
group	Optional. Defaults to "_anonymous".
lp	Optional. Defaults to "false". Specifies if the compute server will be started with live pricing enabled (true) or disabled (false).
Notes	The name and group pair must be unique in a given user's cluster. You can also pass the parameters as JSON in the body if you prefer. Parameters in the body override the parameters in the URI if both are passed, so if you pass name in both the body and the URI, the one in the body is used.

Example

curl -X POST -u -H "content-type: application/json" -d '{"name": "Analytics", "lp": true, "group": "EQT"}' https://api.derivatives.com/farm/cluster

returns:

{
   "id": "dbf4846a-6769-4b29-a68a-82adc9e0185a",
   "name": "Analytics",
   "group": "EQT"
   "lp": true,
}

Listing Available Nodes

GET cluster

Returns in JSON the user, group name(s), or information about a specific node.

Example 1

curl –X GET -u <user:pw> https://api.derivatives.com/farm/cluster

returns:

{
   "owner": "john",
   "nodes": [
      {
         "id": "dbf4846a-6769-4b29-a68a-82adc9e0185a",
         "name": "Analytics",
         "group": "EQT"
      }
   ]
}

Example 2

You can also list the active groups in your cluster:

curl –X GET –u <user:pw> https://api.derivatives.com/farm/cluster/groups

returns:

{
   "groups": [
   "RISKMGT",
   "PORTMGT",
   "_anonymous"
   ]
}

Stopping a Node

POST cluster/<id>/stop
or
DELETE cluster/<id>

You must pass the node's id to stop it.

Parameters

Embed the node id in the URL.

When you stop a node, it disconnects any process connected to it. The compute server may finish processing the request on which it it was working.

Example 1

curl -X POST -u <user:pw> https://api.derivatives.com/farm/cluster/dbf4846a-6769-4b29-a68a-82adc9e0185a/stop

success returns:

{
"id": "dbf4846a-6769-4b29-a68a-82adc9e0185a"
}

Example 2

curl -X DELETE -u <user:pw> https://api.derivatives.com/farm/cluster/dbf4846a-6769-4b29-a68a-82adc9e0185a

success returns:

{
"id": "dbf4846a-6769-4b29-a68a-82adc9e0185a"
}

Invoking an IFP App

An uncommon and valuable feature of Imagine's REST API is that you can author and deploy your own services using the IFP's rich primitives and the JavaScript programming language. Your cluster must have at least one node already running in it to use this resource.

GET app/<appName>/<exportedFunction>

Any IFP JavaScript function that follows certain conventions for calling and returning data can be called here. The function name must be exported, and the function should accept a "request" object. The function must return an object which is passed back to the caller as JSON. You cannot return a simple string or number, it must be an object.

Parameters

When an app is invoked it is passed a "request" object. This object has two notable properties. The property "parameters" is populated from the query string in the URL. The property "body" is populated from the data passed by the POST command. You can see this demonstrated in Examples 2 and 3 below.

The following IFP JavaScript system.in and system.out objects are not available when accessed from the REST API.

Example 1

Round trip to an IFP App.

curl –X GET -u <user:pw> https://api.derivatives.com/farm/app/hello/world

Example 1 JavaScript App "hello.js"

function world(request) {
return { value: "Hello World" };
}
exports['world'] = world

returns:

{
"value": "Hello World"
}

Example 2

Passes data to the app using the query string. The data is provided in the "parameters" property of the request object.

curl –X GET -u <user:pw> https://api.derivatives.com/farm/app/echo/echo?say=hello

Example 2 JavaScript App "echo.js"

function echo(request) {
return request;
}
exports['echo'] = echo;

returns:

{
   "body": null,
   "id": "984d3dee-2317-4852-9300-585632115993",
   "originalRequestId": null,

   "parameters": {
   "say": [
      "hello"
   ]
},

   "routing": "unicast",
   "targetGroupName": null,
   "targetNodeId": null,
   "targetNodeName": null,
   "type": "synchronous",
   "uri": "/echo/echo"
}

Example 3

Passes data to the app using a POST. The data is provided in the "body" property of the request object. You must pass the correct 'content-type' header. Currently, 'application/json' is available.

curl –X -H "content-type: application/json" POST -d '{"name":"ringo"}' -u <user:pw> https://api.derivatives.com/farm/app/echo/echo

Example 3 JavaScript App "echo.js"

function echo(request) {
return request;
}
exports['echo'] = echo;

returns:

{
   "originalRequestId": null,
   "targetNodeName": null,
   "body":{
   "name": "ringo"
   },
   "parameters": {

   },
   "id": "20420334-7099-4a9e-9955-d299fece927e",
   "routing": "unicast",
   "targetGroupName": null,
   "uri":"/echo/echo",
   "type":"synchronous",
   "targetNodeId":null
}

Dispatching Requests

As of this writing, the REST API uses a round-robin scheduling algorithm. It also offers the ability to route requests to specific nodes or groups of nodes. You might use this to optimize performance when particular data is loaded into a particular node. The REST API recognizes special HTTP extension headers that tell it to route requests to specific nodes or groups. You may send a request to a specific node by its id. You may send a request to a node in a collection of nodes by name or group.

Extension Request Headers
Extension Request Headers	Use these headers to specify which node the request should be sent to.
X-Target-Node-Id	Send the request to a specific node identified by UUID.
X-Target-Node-Name	Send the request to a node with this name. If you do not also specify "X-Target-Group-Name" the group will only look in the anonymous group.
X-Target-Group-Name	Send the request to any node with this group name.
Extension Response Headers
X-Request-Id	The id of the request that was received.
X-Response-Node-Id	The id of the node that received the request.
X-Target-Group-Name	The name of the group that was requested and used.

Example

curl –X GET -u <user:pw> -H "X-Target-Node-Name:Analytics" https://api.derivatives.com/farm/app/echo/echo?say=hello

Error Messages

Errors from the REST API are returned as a JSON array.

Example error

{
"errors": [
{
"id": "ede6d706-115a-40b2-885f-da2c8090fdea",
"message": "No nodes exist in this cluster."
}
]
}

Example error when an IFP App throws an exception

{
"errors": [
{
   "file": "<unknown>",
   "line": 0,
   "message": "uncaught exception: your exception message here"
}
]
}

REST API Frequently Asked Questions

Q. When I try to run an app, why do I get the error, "No nodes exist in this cluster"?

A. You must first start a node (by POSTing to cluster) before you can use that node to invoke an app.

Q. When I try to start a node, why do I get the error "Unable to start compute server node"?

A. Error messages are currently being updated for greater clarity. In the meantime:

Are you trying to start the node with lp=true without having access to live pricing? If you don't have access to live prices in the GUI, you don't have access to them from web services either, so use lp=false instead.
Has the environment run out of licenses? E-mail restdoc@imaginesoftware to ask.

Q. When I try to run an app why do I get the error "No handler found. Please make sure the handler exists and is error free"?

A. There are three usual causes for this:

Does the app file name match the request? Is the function in that file exported and does its name match the request?
Have you created the app in the same environment (production, preview) and username that you are running the web service in?
Are there syntax or other errors in the script?