Skip to content

Workspace

Working with Projects

Endpoint: project(s)

With the workspace/projects endpoint, the user can get a list of all available projects in the workspace or create a new project to be stored in the workspace. Adding a scenario to an existing project can be achieved with the workspace/scenarios endpoint.

Example Code
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
import requests

with requests.Session() as session:
    # Login and update the http header with the access token (see above)

    # Retrieve a list of all projects existing projects
    response = session.get("https://sesam.co4e.com/api/v1/workspace/projects")
    all_projects = response.json()

    # Create a new project
    data = {"name": "A new project", "comment": "An example project"}
    response = session.post("https://sesam.co4e.com/api/v1/workspace/projects", data=data)

The schema for the json response (all_projects) is described in the schema file.

The workspace/project/{project_id} endpoint is intended for getting project properties (e.g. name or scenarios), modifying properties and deleting an existing project from the workspace. The project id can be obtained from the list of all projects provided by the workspace/projects endpoint.

Example Code
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
import requests

with requests.Session() as session:
    # Login and update the http header with the access token (see above)

    # Get the properties of project with id = 12 (for example)
    project_id = 12
    response = session.get("https://sesam.co4e.com/api/v1/workspace/projects/" + project_id)
    project = response.json()

    # Modify a project (rename the project)
    data = {"name": "New name"}
    response = session.patch("https://sesam.co4e.com/api/v1/workspace/projects/" + project_id, data=data)

    # Delete a project
    response = session.delete("https://sesam.co4e.com/api/v1/workspace/projects/" + project_id)

Working with Scenarios

Similar to the projects, the workspace endpoints allow to work with available scenarios. They can be retrieved, modified and deleted.

Note

New scenarios are not created with the workspace endpoints. The creation of a scenario can be done with the builder endpoints instead.

Endpoint: scenario(s)

The workspace/scenarios endpoint provides a list of all available scenarios with their properties.

sequenceDiagram
    participant C as Client
    participant S as SESAM API
    Note over C,S: Retrieve scenarios from the workspace
    C->>+S: GET workspace/scenarios
    S->>-C: list of all scenarios
Example Code
1
2
3
4
5
6
7
8
import requests

with requests.Session() as session:
    # Login and update the http header with the access token (see above)

    # Retrieve a list of all scenarios
    response = session.get("https://sesam.co4e.com/api/v1/workspace/scenarios")
    all_scenarios = response.json()

Refining your interaction with a specific scenario is made possible through the workspace/scenario/{scenario_id} endpoint. By supplying the scenario ID as a URL parameter, you gain access to a spectrum of actions including retrieving properties, updating them, and deleting the scenario altogether.

sequenceDiagram
    participant C as Client
    participant S as SESAM API
    Note over C,S: Retrieve scenario with id = 37 from the workspace
    C->>+S: GET workspace/scenarios/37
    S->>-C: properties of scenario 37
    C->>+S: PATCH workspace/scenarios/37 { ... }
    S->>-C: updated properties of scenario 37
    C->>+S: DELETE workspace/scenarios/37
    S->>-C: OK
Example Code
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
import requests

with requests.Session() as session:
    # Login and update the http header with the access token (see above)

    # Retrieve properties of scenario 37
    response = session.get("https://sesam.co4e.com/api/v1/workspace/scenarios/37")
    scenario = response.json()

    # Update the name of scenario 37
    data = {"name": "A new scenario name"}
    response = session.patch("https://sesam.co4e.com/api/v1/workspace/scenarios/37", data=data)
    scenario = response.json()

    # Delete scenario 37
    response = session.delete("https://sesam.co4e.com/api/v1/workspace/scenarios/37")

Endpoint: builtin-scenario(s)

In addition to the scenarios built by a user, SESAM also ships with built-in scenarios, which were contributed by external parties. These scenarios are also visible in the workspace of registered users, but they can be neither modified nor deleted or downloaded. The workspace/builtin-scenarios endpoint provides a list of all available built-in scenarios (similar to the workspace/scenarios endpoint).

Example Code
1
2
3
4
5
6
7
8
import requests

with requests.Session() as session:
    # Login and update the http header with the access token (see above)

    # Retrieve a list of all built-in scenarios
    response = session.get("https://sesam.co4e.com/api/v1/workspace/builtin-scenarios")
    all_builtin_scenarios = response.json()

The workspace/builtin-scenario/{scenario_id} endpoint is similar to the workspace/scenarios/{scenario_id} endpoint, as it takes a scenario id as a parameter in the url and provides a list of all properties of the builtin scenario as a result.

Example Code
1
2
3
4
5
6
7
8
import requests

with requests.Session() as session:
    # Login and update the http header with the access token (see above)

    # Retrieve properties of built-in scenario 4
    response = session.get("https://sesam.co4e.com/api/v1/workspace/builtin-scenarios/4")
    builtin_scenario = response.json()

Endpoint: duplicate-scenario

You may need to duplicate a scenario to modify and simulate it, enabling you to observe variations in the simulation results. This duplication functionality is facilitated through the workspace/duplicate-scenario/{scenario_id} endpoint. It takes a scenario id as a parameter in the url and allows to provide a name for the new scenario as part of the POST request body. The duplication is only allowed for scenarios owned by the current user.

Endpoint: scenario-zip

The workspace/scenario-zip/{scenario_id} endpoints allows to download a scenario from the workspace as a ZIP archive. Calling this endpoint with the scenario id as an url parameter triggers a background task, which is responsible for creating the archive and providing the download link.

Note

The scenario download as a ZIP archive is only supported for user generated scenarios. Built-in scenarios cannot be downloaded as a ZIP archive.

The execution of the background task may take some time and depends on the size of the scenario to be prepared for download. Clients can request the status of this task with the workspace/scenario-zip-status endpoint.

After the background task finished its execution, it will signal its success with a state: "SUCCESS" in the response. It will also provide the download url in the download_url field in the response.

sequenceDiagram
    participant C as Client
    participant S as SESAM API
    Note over C,S: Download scenario with id = 13 as a ZIP archive
    C->>+S: GET workspace/scenario-zip/13
    S->>-C: status_url for task status
    loop until state == "SUCCESS"
        C->>+S: GET status_url
        S->>-C: { ... state, download_url, ...} 
    end

Here is an example python code for creating a zip archive of an existing scenario with the id 13.

Example Code
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
import time

import requests

with requests.Session() as session:
    # Login and update the http header with the access token (see above)

    # Trigger zip creation for scenario 13
    response = session.get("https://sesam.co4e.com/api/v1/workspace/scenario-zip/13")

    # Retrieve the endpoint to query the task status
    status_url = response.json().get("status_url")

    # Check if zip has been created
    download_url = None
    while not download_url:
        response = session.get(status_url)
        # Check if zip creation task finished
        if response.json().get("state", "") == "SUCCESS":
            download_url = response.json().get("download_url")
        else:
            # Delay the next polling
            time.sleep(0.5)

    # Zip archive can be retrieved from URL in download_url

Working with Simulations

Similar to the projects and scenario, there are also endpoints to retrieve, modify and delete simulations.

Note

New simulations are not created with the workspace endpoints. The creation of a simulation can be done with the simulator endpoints instead.

Endpoint: simulations

The workspace/simulations endpoints provides a list of all available simulations with their properties.

sequenceDiagram
    participant C as Client
    participant S as SESAM API
    Note over C,S: Retrieve simulations from the workspace
    C->>+S: GET workspace/simulations
    S->>-C: list of all simulations
Example Code
1
2
3
4
5
6
7
8
import requests

with requests.Session() as session:
    # Login and update the http header with the access token (see above)

    # Retrieve a list of all scenarios
    response = session.get("https://sesam.co4e.com/api/v1/workspace/simulations")
    all_simulations = response.json()

A more fined grained interaction with a single, existing simulation can be achieved with the workspace/simulations/{simulation_id} endpoint. It requires the simulation id as an url parameter and offers to retrieve the properties, update its properties and delete the simulation.

sequenceDiagram
    participant C as Client
    participant S as SESAM API
    Note over C,S: Retrieve simulation with id = 37 from the workspace
    C->>+S: GET workspace/simulations/37
    S->>-C: properties of simulation 37
    C->>+S: PATCH workspace/simulations/37 { ... }
    S->>-C: updated properties of simulation 37
    C->>+S: DELETE workspace/simulations/37
    S->>-C: OK
Example Code
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
import requests

with requests.Session() as session:
    # Login and update the http header with the access token (see above)

    # Retrieve properties of simulation 37
    response = session.get("https://sesam.co4e.com/api/v1/workspace/simulations/37")
    simulation = response.json()

    # Update the name of simulation 37
    data = {"name": "A new simulation name"}
    response = session.patch("https://sesam.co4e.com/api/v1/workspace/simulations/37", data=data)
    simulation = response.json()

    # Delete simulation 37
    response = session.delete("https://sesam.co4e.com/api/v1/workspace/simulations/37")

Endpoint: simulation-run-zip

Similar to the download of a scenario as a ZIP archive via the workspace/scenario-zip endpoint, raw outputs and other results from a single simulation run can also be retrieved as a ZIP archive from the workspace. This can be achieved by the workspace/simulation-run-zip/{simulation_run_id} endpoint. It works in a similar fashion as the workspace/scenario-zip endpoint, as it triggers a background task to collect the output files and build the archive. The workspace/simulation-run-zip-status endpoint can be used in inquire about the execution status of the background task and retrieve the download uri after its successful completion.

sequenceDiagram
    participant C as Client
    participant S as SESAM API
    Note over C,S: Download outputs of simulation with id = 13
    C->>+S: GET workspace/simulation-run-zip/13
    S->>-C: status_url for task status
    loop until state == "SUCCESS"
        C->>+S: GET status_url
        S->>-C: { ... state, download_url, ...} 
    end

Here is an example python code for creating a zip archive of the outputs of a simulation with the id 13.

Example Code
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
import time

import requests

with requests.Session() as session:
    # Login and update the http header with the access token (see above)

    # Trigger zip creation for simulation 13
    response = session.get("https://sesam.co4e.com/api/v1/workspace/simulation-run-zip/13")

    # Retrieve the endpoint to query the task status
    status_url = response.json().get("status_url")

    # Check if zip has been created
    download_url = None
    while not download_url:
        response = session.get(status_url)
        # Check if zip creation task finished
        if response.json().get("state", "") == "SUCCESS":
            download_url = response.json().get("download_url")
        else:
            # Delay the next polling
            time.sleep(0.5)

    # Zip archive can be retrieved from URL in download_url