forio Toggle navigation

Model Operation API

The Model Operation API allows you to manipulate a run using operations exposed by the model.

The Model Operation API supports the following methods:

The Model Operation API works with the following resources / data structures:

POST

Call an Operation from the Model

You can call operations in the model using the Model Operation API POST method.

Depending on the language in which you have written your model, the methods may need to be exposed (e.g. export for a Julia model) in the model file in order to be called through the API. See Writing your Model.

Method: POST

URI:

  • /v2/model/operation/{run id}

Headers:

Body: JSON object with the required fields:

  • name: Name of operation
  • arguments: Array of arguments to the operation

Return Status:

  • 200: Successful response
  • 400: Invalid request

Return Body: JSON object with the name and arguments passed in, plus the result (return value) of the operation. For a complete list of fields, see the operation record.

Example:

curl -X POST \
    'https://api.forio.com/model/operation/00000152a9aa44e228363a623c14ed07b8da' \
    --header 'Content-Type: application/json' \
    --header 'Authorization: Bearer eyJhbGciOiJSUzI1NiJ9' \
    --data '{ "name": "runmodel", "arguments": ["input string", 25, true] }'

Example Response:

{
    "name": "runmodel",
    "arguments": [ "input string", 25, true ],
    "result": 20.44
}

Notes:

  • If the operation does not take any arguments, you can either omit the arguments field, or pass an empty array. For example: 

      curl -X POST \
      'https://api.forio.com/model/operation/00000152a9aa44e228363a623c14ed07b8da' \
      --header 'Content-Type: application/json' \
      --header 'Authorization: Bearer eyJhbGciOiJSUzI1NiJ9' \
      --data '{ "name": "runmodel", "arguments": [] }'

  • General errors with API usage, such as making a call without appropriate permissions, simply return the appropriate HTTP status code. Specific errors because of a problem with the model operation itself return a complete error record.

OPTIONS

For any Epicenter API, use the OPTIONS method to view reference information on properties and arguments of that API.

Method: OPTIONS

URI:

  • /v2/model/operation

Example:

curl -X OPTIONS 'https://api.forio.com/v2/model/operation'

Data Structure

Operation Record

The POST request for the Model Operation API takes an operation record with the name and arguments of the operation. It returns the operation record with details on the operation called and its result.

Field Required? Description
name yes The name of the model operation called. This is required to be passed in to the POST request. It is always present in the response.
arguments no An array of arguments to the operation called. If the operation does not take any arguments, you can either omit the arguments field, or pass an empty array. It is present in the response only if arguments were passed in to the operation. Each argument can be of any type (including JSON objects), as long as there is a corresponding operation in the model.
result no The return value from the operation. This is not included in the POST request; it may be present in the response. If there is no return value, this field is not included. Note that the return value may or may not also be stored in a model variable, depending on the operation.

**Example Operation Record**

An example operation record returned as a response to a POST request: 

{
    "name": "runmodel",
    "arguments": [ "input string", 25, true ],
    "result": 20.44
}

Error Record

The POST request for the Model Operation API may return an error because of a problem with the operation.

Field Required? Description
run_id yes The unique identifier of the run.
name yes The name of the operation called. This is from the POST request.
arguments no The arguments of the operation called. This is from the POST request.
message yes A summary of how the error occurred. This will typically contain enough information to allow you to correct the error.
error yes Boolean; set to true when an error is returned.
type yes An identifier with more information about what triggered the specific error.
fault no An object with additional specifics of how the error occurred, if available. This may include the fields:
  • cause: Exact cause, if known; amount of information available dependent on the modeling language and the nature of the error. Typically includes type, function, file, and line.
  • context: Additional context, if known; amount of information available dependent on the modeling language and the nature of the error.
  • trace: A stack trace, if available, presented as an array. Each element of the array includes type, function, file, and line.
  • information: An object summarizing the class (from the Epicenter backend implementation) and value of the error. Information from the value object, including type, runId, key, and detail, may populate the top-level record fields type, run_id, name, and arguments respectively.
  • native: Not populated for model errors; returned as null.
  • type: Where the error occured.
  • message: A summary of how the error occurred.

**Example Error Record**

An example error record returned as a response to a POST request that caused a model error: 

{
    "type": "invalid_proc",
    "run_id": "00000152c3df8b67a362e3d5ee96365d95f3",
    "message": "TypeError: setRiskAssignedTo() missing 1 required positional argument: 'index'",
    "name": "setRiskAssignedTo",
    "arguments": "[\"TR-01\"]",
    "error": true,

    "fault": {
        "cause": null,
        "context": null,
        "trace": [
            {
                "type": "python",
                "function": "run",
                "file": "/usr/local/lib/python3.4/dist-packages/epicenter-py3.5.egg/epicenter/worker/worker_thread.py",
                "line": 41
            },
            ... 
        ],
        "information": {
            "class": "com.forio.epicenter.bedrock.utility.json.exception.GridErrorImplication",
            "value": {
                "type": "proc",
                "runId": "00000152c3df8b67a362e3d5ee96365d95f3",
                "key": "setRiskAssignedTo",
                "detail": "[\"TR-01\"]"
            }
        },
        "type": "python",
        "message": "TypeError: setRiskAssignedTo() missing 1 required positional argument: 'index'",
        "native": null
    }
}