About the RASON REST API

The RASON REST API provides a set of simple, easy to use endpoints for defining models, solving them using conventional optimization, Monte Carlo simulation or stochastic optimization, and getting results in JSON. A great way to see the REST API in action is to use our Editor page -- select an example model or enter/edit your own, then click the Create App link to generate a Web page, complete with your model, JavaScript/JQuery code to solve it via AJAX calls to the REST API, and some sample HTML markup.

How to Use the API

For small, simple models (including all the examples on the Editor page) that can be solved in limited memory within 30 seconds of CPU time, you can run an optimization or simulation and get results with a single API call: POST rason.net/api/optimize for optimization, or POST rason.net/api/simulate for simulation. To keep your application response time acceptable to your user, you should use this endpoint judiciously.

For larger models that require more time or memory, you can use separate API calls to (i) upload your model plus data files, creating a model resource on the RASON server, (ii) start an optimization or simulation running, (iii) check on its status and get progress information, and finally (iv) retrieve results when the solution process is complete. If necessary, you can stop a long run in progress with an API call.

Other API calls allow you to diagnose a model to determine its type (linear, quadratic, nonlinear, etc.) and size before solving it (mostly useful in model design and development), retrieve a model resource that you've previously created (including the full text of the model), update the model text of an existing model resource, get a list of all the model resources you've created, and delete a model resource.

Authorization Headers

Every RASON REST API call must include an 'Authorization' header with value 'Bearer ' followed by your account OAuth token, which you can copy and paste from the My Account page. If you use the "Create App" facility on the Editor page, the JavaScript code generated to run your model will include your Authorization header and OAuth tokdn -- it really is a complete application that you can just open and run!

Model Resources and Location Headers

When you create a model resource with POST rason.net/api/model, the response will include a 'Location' header whose value is the model id -- referred to as simply id below, and in the API summary on the Editor page. You can retrieve this header in an AJAX response handler function with jqXHR.getResponseHeader('location') -- see the "Create App" JavaScript code for an example. When you make an API call that requires a model id, you simply substitute the string you get from the Location header for id.

It is your responsibility to delete model resources when you no longer need them. This is easy to do: just use the API call DELETE rason.net/api/model/id. The "Create App" JavaScript code shows you how to make this call. Deleting a model resource also removes any data files that were uploaded when it was created. For Basic (free) accounts, the RASON Server will delete "aging" model resources; for Platform and other accounts, we may eventually charge for model resource storage.

Responses: Solution Status and Results

The RASON Server response to every API call is in JSON. The best way to see how to handle the response in your application is to examine the "Create App" JavaScript code, and use the Editor page to see the actual response when you solve your own model.

When you call GET rason.net/api/model/id/status to check the solution status, the JSON response format is fixed, and easy to examine. For example, if the solution process has completed, you'll get { "status": "Complete" }, so you can check for this with code such as if (response.status == "Complete"). When you call GET rason.net/api/model/id/result to retrieve results, the response includes a fixed portion describing the solution status, and a variable portion that depends on what you ask for in the RASON model.

For example, if you run the example model AirlineHub.json (available in the dropdown list on the Editor page), you'll see the following response:

{
"status" : { "code" : 0, "codeText" : "Solver found a solution. All constraints and optimality conditions are satisfied." },
"variables" : {
 "x" : { "finalValue" : 1.250000 },
 "y" : { "finalValue" : 4.000000 },
 "z" : { "finalValue" : 2.136001 }
},
"objective" : {
 "obj" : { "finalValue" : 2.136001 }
}
}

The fixed part of the response includes the "status" property, which tells you the outcome of the optimization. You can test this with JavaScript code such as if (response.status.code == 0). The variable part of the response includes final values for the three decision variables x, y and z, and the objective being minimized (which is the third variable, z). We got this part of the response because we asked for it in the RASON model -- we included the property finalValue: [] in the definition of the objective and each decision variable.

To retrieve the final value of the objective in your JavaScript code, you would simply reference response.objective.obj.finalValue. If the model had asked for the dual value of x by including the property dualValue: [], your JavaScript code could obtain this value with a reference response.variables.x.dualValue.

CPU Time Limits and Charges

Large optimization and simulation models, or challenging mixed-integer, global optimization, or stochastic optimization models can consume significant amounts of CPU time (especially) and memory. Initially, the RASON service back-end workers run on Azure cloud services with 7GB memory, but we can offer much larger memory service instances, up to 112GB. The RASON service handles CPU time as follows:

Complete List of API Calls

Here is a complete list of RASON REST API calls. You can exercise each of these calls on the Editor page.

POST rason.net/api/diagnoseDiagnose the model in the payload and return its type and size.
POST rason.net/api/optimizeOptimize the model in the payload and immediately return the results.
POST rason.net/api/simulateRun the simulation model in the payload and immediately return the results.
POST rason.net/api/datamineRun the datamining model in the payload and immediately return the results.
POST rason.net/api/decisionRun the decision model in the payload and immediately return the results.
POST rason.net/api/solveRun the model (any type) in the payload and immediately return the results with a OData endpoint.
POST rason.net/api/modelCreate a model resource containing the payload and return the model resource id.
POST rason.net/api/model/nameCreate a named model resource containing the payload and return the model resource id.
GET rason.net/api/modelGet a list of all the model resources for my account and return them as a single JSON array.
GET rason.net/api/model/nameGet a list of all the model resources for name for my account and return them as a single JSON array.
GET rason.net/api/model/name/championGet a list of all the model resources for the champion versions of name for my account and return them as a single JSON array.
GET rason.net/api/model/idRetrieve the model resource id and return the full model text.
PUT rason.net/api/model/nameoridUpdates the previously posted named or unnamed model using the resource ID to contain the payload model text.
PATCH rason.net/api/model/nameoridwith "champion" in the body, marks the model as the current champion.
POST rason.net/api/model/nameorid/optimizeCreates a new instance of the model and starts an optimization of the model in the resource nameorid.
POST rason.net/api/model/nameorid/simulateCreates a new instance of the model and starts a Monte Carlo simulation of the model in the resource nameorid.
POST rason.net/api/model/nameorid/datamineCreates a new instance of the model and starts a data mining task in the resource nameorid.
POST rason.net/api/model/nameorid/decisionCreates a new instance of the model and starts a calculation of the decision table model in the resource nameorid.
POST rason.net/api/model/nameorid/diagnoseCreates a new instance of the model and starts a diagnosis of the model in the resource nameorid.
POST rason.net/api/model/nameorid/solveCreates a new instance of the model, starts a solve (of any problem type) in the resource nameorid and automatically creates an OData endpoint.
GET rason.net/api/model/nameorid/optimizeStart an optimization of the model in the resource nameorid.
GET rason.net/api/model/nameorid/simulateStart a Monte Carlo simulation of the model in the resource nameorid.
GET rason.net/api/model/nameorid/datamineStart a data mining task in the resource nameorid.
GET rason.net/api/model/nameorid/decisionStart a decision table calculation in the resource nameorid.
GET rason.net/api/model/nameorid/diagnoseStart a model diagnosis in the resource nameorid.
GET rason.net/api/model/nameorid/statusGet the status of the last optimization/simulation run for resource nameorid.
GET rason.net/api/model/nameorid/resultGet results from the last optimization/simulation run for resource nameorid.
GET rason.net/api/model/nameorid/result/dataDownload results to an external data file for nameorid.
GET rason.net/api/model/id/stagesGet a list of stages from previously posted workflow for resource id.
GET rason.net/api/model/id/stages/allGet stage info from all (or specific) stages of posted workflow for resource id.
GET rason.net/odata/odatalogReturns a log of odata requests for the requesting user.
GET rason.net/odata/resultReturns the results, in OData format, from a model previously solved with POST rason.net/api/model/id/solve.
GET rason.net/odata/resultsReturns RASON models on a user’s account with persistent results and composes the OData feed with basic model info.
GET rason.net/odata/solvelogReturns the log of solve requests for the requesting user.
POST rason.net/api/model/nameorid/stopStop the optimization/simulation running for resource nameorid, discard results.
DELETE rason.net/api/model/idDelete the model resource id and any associated data files.
DELETE rason.net/api/model/name/deleteDelete the champion version of the named model resource name and any associated data files.
DELETE rason.net/api/model/name/allDelete all versions of the named model resource name and any associated data files.
DELETE rason.net/api/model/nameorid/runtokenDeletes a run time token for a named (or unnamed) model.