SHOP Server REST API endpoints

iLab Assistant

This document describes the REST API endpoints that are exposed when shop_server_host has been set up as a service on a remote machine. HTTP requests can be made to these endpoint to run SHOP models and retrieve the results using the SHOP JSON data format. For testing purposes on local machines, starting the shop_server_host application in one terminal and sending requests with a small python script using the requests module from another terminal should work:

import requests

# Check that SHOP Server is running by using the GET method on the general path '/'
response = requests.get("http://127.0.0.1:8000/", json={})

# Should get "OK" back, see general endpoint section below
print(response.text)

Initial configuration¶

It is possible to specify a number of command line arguments when starting the SHOP Server application:

Example usage:

./shop_server --listen 127.0.0.1 --port 9000

Note that setting the --max-sessions flag can be important when running many SHOP optimizations in parallel. Remember to carefully select how many threads CPLEX can use in each parallel optimization with the max_num_threads SHOP attribute so that it matches with the available hardware resources. The total number of parallel runs multiplied with max_num_threads should not be larger than the total number of threads on the system, otherwise CPLEX from one session will fight to use the same threads as CPLEX in another. This will be detrimental to calculation times.

Specifying the SHOP and CPLEX log file paths is possible, but the SHOP log messages can also be sent to a specified logging endpoint. When models are infeasible, CPLEX will dump a minimal infeasible problem to the path pointed to by minimal_infeasible_problem_file. This attribute can also be specified in the --minimal-infeasible-problem-file option to SHOP Server.

General¶

SHOP Server implements the following general endpoints for testing purposes:

Session¶

SHOP Server has built in support for running several parallel SHOP optimization sessions. A session is required to hold the SHOP model itself.

SessionSchema:

Example:

{
  "session_id": 1,
  "session_name": "day-ahead bidding 1"
}

Model¶

After a session has been created, a SHOP model can be created and solved in that session.

The ModelSchema mentioned in the model endpoints should be on the SHOP JSON data format. The format has four root nodes (“time”, “model”, “connections”, and “commands”), but not all nodes must be present for a valid POST request if the user wants to build the model in stages. Setting the static topology data with connections first, then setting time resolution and time series data, and finally running commands is therefore a valid option.

ObjectTypeInfoSchema:

If verbose = false, the resulting AttributeInfoSchema is a single string which is the datatype of the attribute. When verbose = true, the AttributeInfoSchema becomes:

Example of ObjectTypeInfoSchema with verbose = false:

{
    "object_type": "reservoir",
    "instances": [
        "Rsv_1",
        "Rsv_2"
    ],
    "attributes": {
        "max_vol": "double",
        "lrl": "double",
        "hrl": "double",
        /* Remaining reservoir attributes... */
    }
}

Example of ObjectTypeInfoSchema with verbose = true:

{
    "object_type": "reservoir",
    "instances": [
        "Rsv_1",
        "Rsv_2"
    ],
    "attributes": {
        "max_vol": {
            "attribute_name": "max_vol",
            "legacy_datatype": "double",
            "is_input": true,
            "is_output": false,
            "x_unit": "MM3",
            "y_unit": "MM3",
            "license_name": "SHOP_OPEN",
            "full_name": "Max volume",
            "data_func_name": "",
            "description": "Maximum volume of the reservoir",
            "documentation_url": "https://docs.shop.sintef.energy/attribute-table.html",
            "example_url_prefix": "https://docs.shop.sintef.energy",
            "example": "",
            "default_value": "0.0",
            "required": false
        },
        /* Remaining reservoir attributes... */
    }
}

The ModelInfoSchema is a map where the object type names of all possible objects in SHOP are keys, and attribute maps are the values. Each attribute map has all possible attribute names for the object type as keys, and verbose AttributesSchemas as values. Unlike the ObjectTypeInfoSchema, instances of the object types are not reported.

The CommandInfoSchema contains all SHOP commands. The available information for each command is the possible command options, a description of possible values, the required license name, the SHOP version the command was added, and a more detailed description. An excerpt is shown below:

{
    "set simtimestep": {
        "options": [],
        "value_description": "double",
        "license_name": "SHOP_SIMULATION",
        "version_added": "16.5.0",
        "description": "Set the length of the internal time steps of the SHOP simulator in seconds (default is 20 sec). (...)"
    },
    "set universal_strict_pq_uploading": {
        "options": [
            "on",
            "off",
            "not_set"
        ],
        "value_description": "",
        "license_name": "SHOP_OPEN",
        "version_added": "16.5.0",
        "description": "Turn on or off the building on strict PQ curve uploading for all generators in all hours. (...)"
    },
        /* Remaining commands... */
}

Logging¶

It is possible to specify a logging endpoint in SHOP Server to catch the SHOP log messages.

LogEndpointSchema:

Example:

{
  "endpoint": "https://my_logging_endpoint.shop.com"
}

LogMessageSchema:

Example:

{
  "message": "Head optimization on.\n",
  "level": "INFO",
  "callerid": "my_session_1"
}

Time resolution¶

The time resolution can be retrieved with a request to the dedicated “/time_resolution” endpoint.

The TimeResolutionSchema is the same as described in the SHOP JSON data standard documentation under “Time”.

Utility commands¶

Some additional commands have been implemented under the /internal endpoint:

The UtilityCommandSchema is generic:

Example:

{
  "args": [
        true,      
        true,
        false
  ]
}