The RASON REST API provides a set of simple, easy to use endpoints for defining models, solving them using conventional optimization, Monte Carlo simulation, stochastic optimization or data mining/forecasting methods 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.
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, simulation, data mining/ forecasting method or calculate a decision table and get results with a single API call: POST rason.net/api/solve. 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 named model resource on the RASON server, (ii) start an optimization, simulation, data mining or decision table model 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. Afterwards you should delete the model.
Other API calls allow you to diagnose a model to determine its type (linear, quadratic, nonlinear, stochastic, 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.
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 token -- it really is a complete application that you can just open and run!
When you create a model resource with POST rason.net/api/model, the response will include a 'Location' header whose value is the model name or 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 name or id, you simply substitute the string you get from within the Location header for nameorid.
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/nameorid. 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.
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/nameorid/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/nameorid/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,
"id": "2590+AirlineHubExample+2021-09-15-20-44-08-732107",
"codeText": "Solver found a solution. All constraints and optimality conditions are satisfied."
},
"variables": {
"x": {
"finalValue": 1.25004
},
"y": {
"finalValue": 4.00001
},
"z": {
"finalValue": 2.136
}
},
"objective": {
"obj": {
"finalValue": 2.136
}
}
}
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.
Here is a complete list of RASON REST API calls. You can exercise these calls on the Editor 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/datamine | Run the datamining model in the payload and immediately return the results. |
| POST rason.net/api/decision | Run the decision model in the payload and immediately return the results. |
| POST rason.net/api/solve | Run the model (any type) in the payload and immediately return the results with a OData endpoint. |
| POST rason.net/api/score | Scores given the fitted PMML/JSON model and new data attached to the request as "form-data". |
| POST rason.net/api/model | Create a model resource containing the payload and return the model resource id. |
| POST rason.net/api/model/name | Create a named 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/name/champion | Gets 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/nameorid | Returns model text for the champion or most recent model or workbook for name or the specific model resource for id. |
| POST rason.net/api/model/nameorid/fitted-info | Sends the fitted model contained within the request body to the RASON server and returns a response. |
| GET rason.net/api/model/nameorid/fitted-info | Returns the name of the fitted model, the format of the fitted model, the model type, the algorithm used to fit the model, the included features and the output variable. |
| GET rason.net/api/model/nameorid/runtoken | Gets a runtime token for a named (or unnamed) model. |
| PUT rason.net/api/model/nameorid | Updates the previously posted named or unnamed model using the resource ID to contain the payload model text. |
| PATCH rason.net/api/model/nameorid | With "champion" in the body, marks the model as the current champion. |
| POST rason.net/api/model/nameorid/optimize | Creates a new instance of the model and starts an optimization of the model in the resource nameorid. |
| POST rason.net/api/model/nameorid/simulate | Creates 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/datamine | Creates a new instance of the model and starts a data mining task in the resource nameorid. |
| POST rason.net/api/model/nameorid/decision | Creates 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/diagnose | Creates a new instance of the model and starts a diagnosis of the model in the resource nameorid. |
| POST rason.net/api/model/nameorid/solve | Creates a new instance of the model, starts a solve (of any problem type) in the resource nameorid and automatically creates an OData endpoint. |
| POST rason.net/api/model/nameorid/score | Scores a fitted PMML/JSON model POSTed to the RASON server given the new data attached to the request. |
| GET rason.net/api/model/nameorid/optimize | Start an optimization of the model in the resource nameorid. |
| GET rason.net/api/model/nameorid/simulate | Start a Monte Carlo simulation of the model in the resource nameorid. |
| GET rason.net/api/model/nameorid/datamine | Start a data mining task in the resource nameorid. |
| GET rason.net/api/model/nameorid/decision | Start a decision table calculation in the resource nameorid. |
| GET rason.net/api/model/nameorid/diagnose | Start a model diagnosis in the resource nameorid. |
| GET rason.net/api/model/nameorid/solve | Accepts an analytic model (optimization, simulation, data mining or decision table) in JSON and places it in the queue to be solved. |
| GET rason.net/api/model/nameorid/status | Get the status of the last optimization/simulation run for resource nameorid. |
| GET rason.net/api/model/nameorid/result | Get results from the last optimization/simulation run for resource nameorid. |
| GET rason.net/api/model/nameorid/result/data | Download results to an external data file for nameorid. |
| POST rason.net/api/interface | Generates an interface for a reusable RASON model (RASON script or Excel workbook) that can be utilized in a decision flow. |
| GET rason.net/api/interface | Generates an interface from a model saved to a OneDrive or Sharepoint account, that can be utilized in a decision flow. |
| GET rason.net/api/model/interface | Generates an interface from an already posted reusable RASON model, that can be utilized in a decision flow. |
| POST rason.net/api/model/excel | Generates a single-stage decision flow with a stage invoking the reusable Excel model that is located on the user's OneDrive or SharePoint account using the named connection created on the user’s www.rason.com account. |
| POST rason.net/api/scoring-model | Generates the script for the RASON Scoring stage by parsing the named fitted model residing on the RASON server or in a OneDrive account or SQL Server. |
| GET rason.net/api/model/nameorid/scoring-model | Generates the script for the RASON Scoring stage by parsing the named fitted model residing on the RASON server or in a OneDrive account or SQL Server. |
| POST rason.net/api/stages | POSTs a list of stages in a decision flow. |
| GET rason.net/api/model/nameorid/stages | Get a list of stages from a previously posted decision flow. |
| POST rason.net/api/stages/{stage} | POSTs a specific {stage} in a decision flow. |
| GET rason.net/api/model/nameorid/stages/{stage} | Returns information about the specified {stage}. |
| GET rason.net/odata/odatalog | Returns a log of odata requests for the requesting user. |
| GET rason.net/odata/result | Returns the results, in OData format, from a model previously solved with POST rason.net/api/model/id/solve. |
| GET rason.net/odata/results | Returns RASON models on a user’s account with persistent results and composes the OData feed with basic model info. |
| GET rason.net/odata/solvelog | Returns the log of solve requests for the requesting user. |
| POST rason.net/api/flow | Generates and returns the flow in the response for the Excel/RASON model attached in the body of the request. |
| GET rason.net/api/flow | Returns the flow in the response for the model on a OneDrive or SharePoint account or for the model attached in the body of the request. |
| POST rason.net/api/model/nameorid/flow | Generates and posts the decision flow for the RASON or Excel model on the user's account. |
| GET rason.net/api/model/nameorid/flow | Returns the generated flow for the RASON or Excel model posted on the user's account. |
| PUT rason.net/api/model/nameorid/flow | Generates and modifies the decision flow for the RASON or Excel model posted on the user's account. |
| POST rason.net/api/model/flow | Generates and publishes the single-stage flow invoking a RASON/Excel model stored on the user's OneDrive/SharePoint account. |
| GET rason.net/api/model/flow | Returns the single-stage flow invoking a RASON/Excel model stored on the user's OneDrive/SharePoint account. |
| PUT rason.net/api/model/flow | Generates and modifies the single-stage flow invoking a RASON/Excel model stored on the user's OneDrive/SharePoint account. |
| POST rason.net/api/model/nameorid/stop | Stop the RASON model running for resource nameorid, discard results. |
| POST rason.net/api/model/nameorid/stop/schedule | Stops a run for the model instance, all future runs and removes the schedule |
| PUT rason.net/api/model/Excel | Updates a previously posted single-stage decision flow POSTed using POST rason.net/api/model/excel?connection-name= |
| DELETE rason.net/api/model/nameorid | Delete the model resource id and any associated data files. |
| DELETE rason.net/api/model/nameorid/runtoken | Deletes a run time token for a named (or unnamed) model. |