Model Operation API

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

You can only call methods on runs that are currently in memory. (For more details, see information on run persistence and on the Model State API, which brings an existing, persisted run from the database back into memory.)

The Operation API supports the following methods:

• POST: Call a method from the model
• OPTIONS: View reference information about the API

See also:

• Error Reporting from Model APIs

POST: Call a Method Exposed by the Model

You can call methods in 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).

Runs must be in memory in order for you to update variables or call operations on them. (See more information on run persistence.) Runs are automatically replayed when you call an operation (method) from the model. (If needed, you can change this behavior in your Model Context file.)

Calling a Method from the Model

---

Method: POST

URI: /model/operation/{run id}

Headers: Content-Type: application/json, Accept: application/json

Body: JSON object with fields name (name of method) and arguments (array of method arguments), e.g. {"name": "myMethodName", "arguments": ["myMethodArgument1", "myMethodArgument2"]}

Return Status: 200 (successful response), 400 (invalid syntax)

Return Body: The method name and arguments passed in, plus the return value of the method.

---

Example:

curl -X POST \
    'https://api.forio.com/model/operation/b662576b-c514-42e0-af9f-61c7316af1a4'
    --header 'Content-Type: application/json' \
    --header 'Accept: 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:

• The result is simply the return value from the method you just called. It may or may not also be stored in a model variable, depending on the method.
• The arguments is an array of all parameters. Each parameter can be of any type (including JSON objects), as long as there is a corresponding operation in the model.

OPTIONS: View Reference Information about the API

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

View Reference Information about the API

---

Method: OPTIONS

URI: /model/operation

---

Example:

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

Error Reporting from Model APIs

The Model APIs — and the APIs built on top of them in the Epicenter stack, such as the Run API — all use the same format for reporting errors from the model.

These are errors because of a problem with a variable or operation. General errors with API usage, such as making a call without appropriate permissions, simply return the appropriate HTTP status code. See each of the Model APIs for specifics.

Errors Messages from the Model

Errors messages generated by the model include:

• status, the HTTP Status Code
• runId, the unique identifier of this run
• errors, an array of the errors

Each element of the errors array includes:

• The specific error that caused the problem with the model. This is one of:
  • invalid_name
  • cannot_set_parameter
  • internal_model_error
  • internal_worker_error
  • file_not_found
• A name with more information about what triggered the specific error. This varies based on the language of your model. For example, for Vensim models this is the name of the variable or operation; for Python models this is the Python language error.
• A message with more information about how the error occurred.

Example

For example, the following API request to update variables (using a Vensim model):

curl -X PATCH \
    'https://api.forio.com/model/variable/e2bf7868-f20e-42a9-8119-8adeb5f5f751' \
    --header 'Content-Type: application/json' \
    --header 'Authorization: Bearer eyJhbGciOiJSUzI1NiJ9' \
    --data '{ "Price": 200, "Bad Var": 35 }'

generates this error message from the model:

{
    "status": 400,
    "runId": "e2bf7868-f20e-42a9-8119-8adeb5f5f751",
    "errors": [
        {
            "error": "invalid_name",
            "message": "Invalid variable name: Bad Var.",
            "name": "Bad Var"
        }
    ]
}

IMPORTANT: Note that for multi-part API requests, part of the request may be completed even if another part of the request returns an error. In the example above, the variable Price is updated, even though the attempt to update the variable Bad Var causes a model error.