Intelligent Services For Energy-Efficient Design and Life Cycle Simulation

Project acronym: ISES ⎪ Project number: 288819 ⎪ Call identifier: FP7-ICT-2011-7 ⎪ Project coordinator: Technische Universität Dresden, Germany

Using the ISES Cloud API

Introduction

This document is intended for developers who want to write client libraries, plugins, and other tools for interacting with ISES API. This guide provides an overview of the API as well as helpful tips on how to use the API.

All calls to the API are unauthenticated, JSON-based, REST requests that use SSL, i.e. URLs begin with https.

Overview

Actions on the ISES cloud API are performed sequentially:

  1. First, project context has to be created in order to identify project to be able to assign actions to that project.
  2. Actions are being performed and order has to be maintained to be able to maintain integrity of the data and the results.
  3. Once actions are finished, result files can be downloaded.

All actions should be triggered through POST!

Security and authentication

User based security is provided by the use of security token which is requested for every access to the ISES VEL API. That means that security token is sent with every call to the API. That is why API is used with TLS encryption in order to prevent unauthorized interception of communication that can be easily decoded otherwise. The security token is provided on request.

To add another layer of protection, the RESTful services in the ISES VEL API are whitelisting allowable methods in order to separate user roles if necessary.

List of available actions/methods

ActionMeaningNotes
start_new_project Method used to start the project and open the project context.
  • default value: none
  • API token: required
  • required parameters: action, token, project name
  • response format: json
upload_building_data Method for uploading data needed to start the passive simulation.
  • default value: none
  • API token: required
  • required parameters: action, token, project id, simulation data files
  • response format: json
prepare_simulation_data Method for preparing data for the passive simulation.
  • default value: none
  • API token: required
  • required parameters: action, token, project id
  • response format: json
start_passive_simulation Method for starting the passive simulation.
  • default value: none
  • API token: required
  • required parameters: action, token, project id
  • response format: json
get_status Method that returns the current status of the simulation.
  • default value: none
  • API token: required
  • required parameters: action, token, project id
  • response format: json
get_passive_simulation_results Method that returns results of the passive simulation once the simulation is finished.
  • default value: none
  • API token: required
  • required parameters: action, token, project id
  • response format: binary file (zip)
prepare_simulation_matrix Method preparing simulation matrix that is used in sensitivity analysis.
  • default value: none
  • API token: required
  • required parameters: action, token, project id, simulation matrix data files
  • response format: json
start_sensitivity_analysis Method for starting the sensitivity analysis.
  • default value: none
  • API token: required
  • required parameters: action, token, project id
  • response format: json
get_sensitivity_analysis_results Method that returns results of the sensitivity analysis once the simulation is finished.
  • default value: none
  • API token: required
  • required parameters: action, token, project id
  • response format: binary file (zip)
start_detailed_analysis Method for starting detailed analysis.
  • default value: none
  • API token: required
  • required parameters: action, token, project id
  • response format: json
get_detailed_analysis_results Method that returns results of the detailed analysis once the analysis is finished.
  • default value: none
  • API token: required
  • required parameters: action, token, project id
  • response format: binary file (zip)
start_cfd_analysis Method for starting CFD analysis.
  • default value: none
  • API token: required
  • required parameters: action, token, project id
  • response format: json
get_cfd_analysis_results Method that returns results of the CFD analysis once the analysis is finished.
  • default value: none
  • API token: required
  • required parameters: action, token, project id
  • response format: binary file (zip)
start_riuska_simulation Method for starting sensitivity analysis from Granlund Riuska client application.
  • default value: none
  • API token: required
  • required parameters: action, token, project id, simulation parameters matrix data file
  • response format: json
get_riuska_simulation_results Method that returns ensitivity analysis results.
  • default value: none
  • API token: required
  • required parameters: action, token, project id
  • response format: binary file (zip)

Developer specifications

Methods/actions

start_new_project

input parameters

action: start_new_project
token: (string)
project_name: (string)

example response

json: {
  "action":"start_new_project",
  "status":"OK",
  "project_id": (string)
}

upload_building_data

input parameters

action: upload_building_data
token: (string)
project_id: (string)
file: (zip binary file - must contain ISES_project.ifc and ISES_project.rdf)

example response

json: {
  "action":"upload_building_data",
  "status":"OK",
  "project_id": (string)
}

prepare_simulation_data

input parameters

action: prepare_simulation_data
token: (string)
project_name: (string)

example response

json: {
  "action":(string) "prepare_simulation_data",
  "status":(string) "OK",
  "description":(string) "X job(s) submitted to cluster Y.",
  "project_id": (string)
}

start_passive_simulation

input parameters

action: (string) start_passive_simulation
token: (string)
project_name: (string)

example response

json: {
  "action":"start_passive_simulation",
  "status": (string) "OK",
  "description":(string) "X job(s) submitted to cluster Y.",
  "project_id": (string)
}

get_passive_simulation_results

input parameters

action: get_passive_simulation_results
token: (string)
project_id: (string)

example response

(zip binary file)

get_status

input parameters

action: get_status
token: (string)
project_name: (string)

example response

json: {
  "action":"get_status",
  "status": (string) "idle/running",
  "description: (array):
    "prepare_simulation_data": (string) "Done./Running./Not started./Error.",
    "passive_simulation": (string) "Done./Running./Not started./Error.",
    "simulation_matrix:" (string) "Done./Running./Not started./Error.",
    "sensitivity_analysis" (string) "Done./Running./Not started./Error.",
    "detailed_analysis" (string) "Done./Running./Not started./Error.",
    "cfd_analysis" (string) "Done./Running./Not started./Error.",
    "riuska_simulation" (string) "Done./Running./Not started./Error.",
  "project_id":"(string)"
}

prepare_simulation_matrix

input parameters

action: prepare_simulation_matrix
token: (string)
project_id: (string)
simulation matrix data files (.zip)
          

example response

json: {
  "action":" prepare_simulation_matrix ",
  "status": (string) "Preparing simulation matrix.",
  "project_id": (string)
}
          

start_sensitivity_analysis

input parameters

action: start_sensitivity_analysis
token: (string)
project_id: (string)
          

example response

json: {
  "action":" start_sensitivity_analysis ",
  "status": (string)"X job(s) submitted to cluster Y.",
  "project_id": (string)
}
          

get_sensitivity_analysis_results

input parameters

action: get_sensitivity_analysis_results
token: (string)
project_name: (string)

example response

(zip binary file)
          

start_detailed_analysis

input parameters

action: start_detailed_analysis
token: (string)
project_id: (string)
          

example response

json: {
  "action":" start_detailed_analysis ",
  "status": (string)"X job(s) submitted to cluster Y.",
  "project_id": (string)
}
          

get_detailed_analysis_results

input parameters

action: get_detailed_analysis_results
token: (string)
project_name: (string)

example response

(zip binary file)
          

start_cfd_analysis

input parameters

action: start_cfd_analysis
token: (string)
project_id: (string)
          

example response

json: {
  "action":" start_cfd_analysis ",
  "status": (string)"X job(s) submitted to cluster Y.",
  "project_id": (string)
}
          

get_cfd_analysis_results

input parameters

action: get_cfd_analysis_results
token: (string)
project_name: (string)

example response

(zip binary file)
          

start_riuska_simulation

input parameters

action: start_riuska_simulation
token: (string)
project_id: (string)
          

example response

json: {
  "action":" start_riuska_simulation ",
  "status": (string)"X job(s) submitted to cluster Y.",
  "project_id": (string)
}
          

get_riuska_simulation_results

input parameters

action: get_riuska_simulation_results
token: (string)
project_name: (string)

example response

(zip binary file)