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 Try It 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 Try It 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 Try It 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 Try It 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 Try It 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 Try It 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 RST API calls. You can exercise each of these calls on the Try It page.

POST rason.net/api/diagnose

Diagnose the model in the payload and return its type and size.

POST rason.net/api/optimize

Optimize the model in the payload and immediately return the results.

POST rason.net/api/simulate

Run the simulation model in the payload and immediately return the results.

POST rason.net/api/model

Create a model resource containing the payload and return the model resource id.

GET rason.net/api/model

Get a list of all the model resources for my account and return them as a single JSON array.

GET rason.net/api/model/id

Retrieve the model resource id and return the full model text.

PUT rason.net/api/model/id

Update the model resource id to contain the payload model text.

GET rason.net/api/model/id/optimize

Start an optimization of the model in the resource id.

GET rason.net/api/model/id/simulate

Start a Monte Carlo simulation of the model in the resource id.

GET rason.net/api/model/id/status

Get the status of the last optimization/simulation run for resource id.

GET rason.net/api/model/id/result

Get results from the last optimization/simulation run for resource id.

POST rason.net/api/model/id/stop

Stop the optimization/simulation running for resource id, discard results.

DELETE rason.net/api/model/id

Delete the model resource id and any associated data files.