|
|
REST Endpoint: POST: https://rason.net/api/model
A REST API endpoint that creates an unnamed or named resource ID for
- a RASON model,
- an Excel optimization/simulation/decision table/data science model
- a data science fitted model (RASON or PMML)
and returns a Location header with the resource ID. If "modelName":"myModelName" exists in the body of the RASON model or if the model name
is appended to this endpoint (POST https://rason.net/api/model/{myModelName}), then this REST API endpoint will create a named resource. The model,
"myModelName", must be a RASON model and not a fitted model. Model names are case sensitive.
The returned model ID URL facilitates subsequent calls to the RASON REST API endpoints necessary for manipulating your model
(i.e. perform an optimization, run a simulation, check the status of the model, get results, etc.).
Note: When POST rason.net/api/model is used to POST an Excel model, the Excel model is uploaded and stored on the Rason server.
Below is a brief explanation of the returned properties
- modelId: The unique identifier for the model
-
modelName: The name of the model taken from the model text. When using POST rason.net/api/model/<name>
- the name from the url is validated against the name in the model, if specified.
- ModelDescr: The model description taken directly from the model text
- ModelFiles: The list of files used by the model as taken from the model text.
- RuntimeToken: Lists any runtime token associated with this model
- ModelType: Lists the type of model such as "origin", "version", "instance".
- “origin” – the initially posted model
- “version” – means that this model is a version of a previously POSTed or PUT model
- “instance” – these are models created whenever a model is run.
- modelKind: Lists the kind of model such as "fitted", "excel" or "rason".
- “fitted” – fitted Data Science model in PMML/JSON format
- “excel” – models defined in Excel language
- “rason” – models defined in RASON language
-
isChampion: True only if model has been specifically marked as the “Champion” using the REST API endpoint
PATCH rason.net/api/model/{nameorid}.
-
parentModelId: Identifies the model from which this model is derived. In the case of “Origin” models, this is always empty. Otherwise,
this property identifies the model used to create this model. For example, if a user POST’s a model and then PUT’s another version of this model,
"parentModelId" of the version will be the modelId of the originally posted model. Similar logic holds for posting versions of version and instances
of version.
-
queryString: The query string associated with the model when it was created. In the case of unnamed models, this will change throughout the model’s lifecycle. A user may post an unnamed model with a particular query string but then solve the model with another. In the case of named models, this is the query string associated with the action used to create the model. A model could be posted with one query string, have several versions with different query strings and associated instances with yet another query string. If a particular version or instance doesn’t have a query string, it will inherit the query string of the parent.
A model may be posted with raw body or form-data.
Posting with raw body:
-
When a model is posted with the raw RASON script, the model acquires ModelType=Origin and ModelKind=Rason properties.
-
When a data science JSON fitted model is posted, the model acquires ModelType=Origin, ModelKind=Fitted properties. The model is
checked for validity (using Frontline's standards) and modelName is inferred from the model JSON text.
-
When a data science PMML fitted model is posted (by specifying Contet-Type=application/xml), the model acquires ModelType=Origin,
ModelKind=Fitted properties. The XML (not PMML) is checked for validity and ModelName is inferred from the model XML text.
- All other POSTS are considered as unrecognized ModelKind.
Posting with Content-Type=multipart/form-data:
Note: Click here to find common MIME types.
Excel Mime Types (case-insensitive):
- "application/vnd.ms-excel"; // .xls, .xlt, .xla
- "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"; // .xlsx
- "application/vnd.openxmlformats-officedocument.spreadsheetml.template"; // .xltx
- "application/vnd.ms-excel.sheet.macroEnabled.12"; // .xlsm
- "application/vnd.ms-excel.template.macroEnabled.12"; // .xltm
- "application/vnd.ms-excel.addin.macroEnabled.12"; // .xlam
- "application/vnd.ms-excel.sheet.binary.macroEnabled.12"; // .xlsb
-
URL:
https://rason.net/api/model
https://rason.net/api/model/{myModelName}
Example: https://rason.net/api/model/TestModelName
https://rason.net/api/model/{myModelID}
Example: https://rason.net/api/model/123456789
- Method: POST
-
URL Params
Required: None
Optional: If uploading an Excel optimization/simulation/decision table model use: ?worksheet=<name>
where <name> is the name of the worksheet.
-
Headers:
Required: Authorization - Example: Authorization: bearer {your RASON token}
Optional: None
-
Data Params:
An unnamed or named* RASON optimization, simulation, data science or decision table model, an unnamed or named data science fitted model,
a data science PMML fitted model (with "xml" or "json" extension) or an Excel workbook. The model may be in "raw body" or "form-data" form.
(See description above.)
*Note: If using the URLs https://rason.net/api/model/{myModelName} or https://rason.net/api/model/{myModelID}, modelName (if present) must
be identical to {myModelName} or {myModelID}, whichever is being passed, otherwise a 400 (Bad Request) will be returned. Alternatively, modelName
may be omitted from the RASON model.
{
variables: {
"d9:f9": {
lower: 0, value: 0, finalValue: []
}
},
data: {
"d17:f17": {
value: [[75, 50, 35]]
},
"d11:f11": {
value: [[1, 1, 0]]
},
"d12:f12": {
value: [[1, 0, 0]]
},
"d13:f13": {
value: [[2, 2, 1]]
},
"d14:f14": {
value: [[1, 1, 0]]
},
"d15:f15": {
value: [[2, 1, 1]]
}
},
constraints: {
c11: {
formula: "sumproduct(d9:f9, d11:f11)",
upper: 450
},
c12: {
formula: "sumproduct(d9:f9, d12:f12)",
upper: 250
},
c13: {
formula: "sumproduct(d9:f9, d13:f13)",
upper: 800
},
c14: {
formula: "sumproduct(d9:f9, d14:f14)",
upper: 450
},
c15: {
formula: "sumproduct(d9:f9, d15:f15)",
upper: 600
}
},
objective: {
d18: {
type: "maximize",
formula: "sumproduct(d9:f9, d17:f17)",
finalValue: []
}
}
}
-
Success Response
Code: 201 (Created)
-
Response Example: (RASON data science model submitted as form-data as Text with content name "RasonModel" and two additional data files.)
{
"ModelId": "2590+DecisionTreeClassification3+2020-06-01-21-20-00-698446",
"ModelName": "DecisionTreeClassification3",
"ModelDescr": "classification: decision tree",
"ModelFiles": [
{
"fileName": "hald-small-binary-train.txt",
"isOnServer": true
},
{
"fileName": "hald-small-binary-valid.txt",
"isOnServer": true
},
{
"fileName": "classification-decision-tree.xml",
"isOnServer": false
},
{
"fileName": "classification-decision-tree.json",
"isOnServer": false
}
],
"RuntimeToken": "",
"ModelType": "Origin",
"ModelKind": "Rason",
"IsChampion": false,
"ParentModelId": null,
"QueryString": ""
}
-
Response Example: (An Excel optimization model submitted as form-data as "File".)
{
"ModelId": "2590+Blending(Opt)+2020-06-01-21-23-30-714655",
"ModelName": "Blending(Opt)",
"ModelDescr": "",
"ModelFiles": [],
"RuntimeToken": "",
"ModelType": "Origin",
"ModelKind": "Excel",
"IsChampion": false,
"ParentModelId": null,
"QueryString": ""
}
-
Response Example: (A data science fitted model submitted as raw body.)
{
"ModelId": "2590+LogisticRegressionFitted1+2020-06-01-21-25-05-231970",
"ModelName": "LogisticRegressionFitted1",
"ModelDescr": "",
"ModelFiles": [],
"RuntimeToken": "",
"ModelType": "Origin",
"ModelKind": "Fitted",
"IsChampion": false,
"ParentModelId": null,
"QueryString": ""
}
-
Response Example: (A portfolio optimization model submitted using https://rasonrestapi2core.azurewebsites.net/api/model/PortfolioModel. The property modelName was not
present in the RASON model. The name of the model was obtained from the URL request, PortfolioModel.
{
"ModelId": "2590+PortfolioModel+2024-01-04-15-01-29-496562",
"ModelName": "PortfolioModel",
"ModelDescr": "Quadratic RASON Model Example",
"ModelFiles": [],
"RuntimeToken": "",
"ModelType": "Origin",
"ModelKind": "RASON",
"InstanceType":null,
"IsChampion": false,
"ParentModelId": null,
"QueryString": "",
"ModelContainer": null,
"Permissions": null
}
-
Response Example: (A portfolio optimization model submitted using https://rasonrestapi2core.azurewebsites.net/api/model/987654321. The property modelName was not
present in the RASON model. The name of the model was obtained from the URL request, 987654321.
{
"ModelId": "2590+987654321+2024-01-09-15-16-56-778314",
"ModelName": "987654321",
"ModelDescr": "Quadratic RASON Model Example",
"ModelFiles": [],
"RuntimeToken": "",
"ModelType": "Origin",
"ModelKind": "RASON",
"InstanceType":null,
"IsChampion": false,
"ParentModelId": null,
"QueryString": "",
"ModelContainer": null,
"Permissions": null
}
Attaching Data Files using POST: https://rason.net/api/model
The REST endpoint POST https://rason.net/api/model may also be used to submit one or more external data files, such as an Excel file, ms-access, mssql, odbc, or oracle database, OData endpoint, or a CSV, JSON, or XML file.
Below is an example that illustrates how to upload data files using JavaScript. The example code uses the POST rason.net/api/model endpoint to create a javascript 'FormData' object, set a special "RasonModel" field on the object and append the data files.
submitModelWithDataFiles: function () {
var formData = new FormData(), me = this, request = new
XMLHttpRequest();
formData.append("RasonModel", this.RASONModel);
for (var i = 0; i > this.modelDataFiles.length; ++i) {
formData.append(this.modelDataFiles[i].name, this.modelDataFiles[i],
this.modelDataFiles[i].name);
}
request.onreadystatechange = function () {
if (this.readyState == 4) {
if (this.status == 200 || this.status == 201) {
// model has been posted to the RASON server. enqueue it for
//processing
me.getModelId(this.response, this.statusText, this);
} else {
me.invokeFailed(this, this.statusText, null);
}
}
};
//use the POST rasonnet/api/model endpoint to create a javascript FormData //object
request.open("POST", this.RASONServer + '/model');
request.setRequestHeader('Authorization', this.ajaxOpts.headers['Authorization']);
request.send(formData);
}
See the dataSources section within the RASON Reference Guide for information on how to access this data from within your RASON model.
|