BMI-enbled Web Service Model (BMI)¶

BMI-enabled models are self-describing by uncovering models’ metadata through BMI (Basic Model Interface) functions, developed in CSDMS (Community Surface Dynamics Modeling System). We expose the BMI-enabled models as web services that allow users to access the functionality of BMI-enabled models through web services. A BMI-enabled web service model is composed of a set of REST API endpoints, each of which exposes a BMI function at most cases. One of the usages of BMI-enabled web services models is implemented in integrating these web service models through EMELI-WEB. Currently, BMI-enabled TopoFlow components are exposed as web services.

Endpoints for Available Models¶

GET /bmi/models¶

Return all the available BMI-enabled web service models.

Example request:

GET /bmi/models HTTP/1.1
Host: ecgs.ncsa.illinois.edu/

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
 "models": [
    "channels_diffusive_wave",
    "channels_dynamic_wave",
    "channels_kinematic_wave",
    "met_base"]
}

Test Call

GET /bmi/models/{model}/working¶

Check whether a specific web service model named as model is working.

Parameters:	model (string) – the name of the model

Example request:

GET /bmi/models/met_base/working HTTP/1.1
Host: ecgs.ncsa.illinois.edu/

Example response 1 – when the web service model is working:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "info": true
}

Example response 2 – when the web service model is not working:

HTTP/1.1 200 OK
Content-Type: application/json

{
   "info": false
}

Endpoints for Model Control Functions¶

POST /bmi/models/{model}/instantiate¶

Instantiate the BMI-enabled web service model with name ‘model’ and return back an ID for further web service interactions.

Parameters:	model (string) – the name of the model

Example request:

POST /bmi/models HTTP/1.1
Host: ecgs.ncsa.illinois.edu/

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
 "ID": "fa821dfbc4844559a6d67e910aa58db5"
}

PUT /bmi/models/{model}/{id}/initialize¶

Initialize the BMI-enabled web service model with name model and id after it is instantiated and the configuration file if any is sent to it.

Parameters:	model (string) – the name of the model id (string) – the ID of the model instance, generated when the model is instantiated

Example request:

PUT /bmi/models/met_base/fa821dfbc4844559a6d67e910aa58db5/initialize HTTP/1.1
Host: ecgs.ncsa.illinois.edu/

Example response1 – when the web service model is instantiated:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "status": "initialized",
  "DONE": false,
  "temp_file": "TopoFlow_Meterology_initialized.nc",
  "time": 0.0
}

Example response2 – when it fails:

HTTP/1.1 200 OK
Content-Type: application/json

{
 "info": "Model is not initialized."
}

PUT /bmi/models/{model}/{id}/update¶

Update the BMI-enabled web service model with name model and id after it is initialized.

Query Parameters:
Parameters:	model (string) – the name of the model id (string) – the ID of the model instance, generated when the model is instantiated
	download_updatenc – a boolean value indicating whether a temporary NetCDF file storing the output variable values at the current time should be generated.

Example request:

PUT /bmi/models/met_base/fa821dfbc4844559a6d67e910aa58db5/update?download_updatenc=true HTTP/1.1
Host: ecgs.ncsa.illinois.edu/

Example response1 – when the web service model is updated and generates a NetCDF file:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "status": "updated",
  "DONE": false,
  "temp_file": "TopoFlow_Meterology_updated.nc",
  "time": 6.0
}

Example response2 – when it fails:

HTTP/1.1 200 OK
Content-Type: application/json

{
 "info": "Model is not updated."
}

PUT /bmi/models/{model}/{id}/finalize¶

Finalize the BMI-enabled web service model with name model and id after the simulation is done.

Parameters:	model (string) – the name of the model id (string) – the ID of the model instance, generated when the model is instantiated

Example request:

PUT /bmi/models/met_base/fa821dfbc4844559a6d67e910aa58db5/finalize HTTP/1.1
Host: ecgs.ncsa.illinois.edu/

Example response1 – when the web service model is instantiated:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "status": "finalized",
  "DONE": true,
  "temp_file": "TopoFlow_Meterology_finalized.nc",
  "time": 24.0
}

Example response2 – when it fails:

HTTP/1.1 200 OK
Content-Type: application/json

{
 "info": "Model is not finalized."
}

Endpoints for Model Information Functions¶

GET /bmi/models/{model}/get_input_requirements¶

Return the configuration information about what the model with name model requires for the initialization in RDF triples.

Parameters:	model (string) – the name of the model

GET /bmi/models/{model}/{id}/get_input_var_names¶

Return the inputs of the BMI-enabled web service model with name model and id

Parameters:	model (string) – the name of the model id (string) – the ID of the model instance, generated when the model is instantiated

Example request:

GET /bmi/models/met_base/fa821dfbc4844559a6d67e910aa58db5/get_input_var_names HTTP/1.1
Host: ecgs.ncsa.illinois.edu/

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "inputs": [
    "snowpack__z_mean_of_mass-per-volumn-density",
    "snowpack__depth",
    "snowpack__liquid-equivalent_depth",
    "snowpack__melt_volume_flux"
  ]
}

GET /bmi/models/{model}/{id}/get_output_var_names¶

Return the outputs of the BMI-enabled web service model with name model and id

Parameters:	model (string) – the name of the model id (string) – the ID of the model instance, generated when the model is instantiated

Example request:

GET /bmi/models/met_base/fa821dfbc4844559a6d67e910aa58db5/get_output_var_names HTTP/1.1
Host: ecgs.ncsa.illinois.edu/

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "outputs": [
    "atmosphere_aerosol_dust__reduction_of_transmittance",
    "atmosphere_air-column_water-vapor__liquid-equivalent_depth",
    "atmosphere_bottom_air__brutsaert_emissivity_canopy_factor",
    "atmosphere_bottom_air__temperature"
  ]
}

GET /bmi/models/{model}/{id}/get_config_var_names¶

Return the config variables of the BMI-enabled web service model with name model and id

Parameters:	model (string) – the name of the model id (string) – the ID of the model instance, generated when the model is instantiated

Example request:

GET /bmi/models/met_base/fa821dfbc4844559a6d67e910aa58db5/get_config_var_names HTTP/1.1
Host: ecgs.ncsa.illinois.edu/

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "config": [
    "water-liquid__mass-per-volume_density",
    "model__time_step",
    "land_surface__temperature",
    "land_surface__emissivity"
  ]
}

GET /bmi/models/{model}/{id}/get_attributes¶

Return the attributes of the BMI-enabled web service model with name model and id

Parameters:	model (string) – the name of the model id (string) – the ID of the model instance, generated when the model is instantiated

Example request:

GET /bmi/models/met_base/fa821dfbc4844559a6d67e910aa58db5/get_attributes HTTP/1.1
Host: ecgs.ncsa.illinois.edu/

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "attributes": {
    "author_name": "Scott D. Peckham",
    "cfg_extension": "_meteorology.cfg",
    "cfg_template_file": "Meteorology.cfg.in",
    "cmt_var_prefix": "/Meteorology/Input/Var/",
    "comp_name": "Meteorology",
    "dialog_title": "Meteorology: Method 1 Parameters",
    "grid_type": "uniform",
    "gui_xml_file": "/home/csdms/cca/topoflow/3.1/src/share/cmt/gui/Meteorology.xml",
    "model_family": "TopoFlow",
    "model_name": "TopoFlow_Meteorology",
    "step_method": "explicit",
    "time_step_type": "fixed",
    "time_units": "seconds",
    "version": "3.1"
  }
}

Endpoints for Temporal Information Functions¶

GET /bmi/models/{model}/{id}/get_time_step¶

Return the time step of the BMI-enabled web service model with name model and id after it is initialized.

Parameters:	model (string) – the name of the model id (string) – the ID of the model instance, generated when the model is instantiated

Example request:

GET /bmi/models/met_base/fa821dfbc4844559a6d67e910aa58db5/get_time_step HTTP/1.1
Host: ecgs.ncsa.illinois.edu/

Example response1: when it succeeds:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "step": 0.6
}

Example response2: when it fails:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "info": "time step cannot be obtained"
}

GET /bmi/models/{model}/{id}/get_time_units¶

Return the time units of the BMI-enabled web service model with name model and id after it is initialized.

Parameters:	model (string) – the name of the model id (string) – the ID of the model instance, generated when the model is instantiated

Example request:

GET /bmi/models/met_base/fa821dfbc4844559a6d67e910aa58db5/get_time_units HTTP/1.1
Host: ecgs.ncsa.illinois.edu/

Example response1: when it succeeds:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "units": "second"
}

Example response2: when it fails:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "info": "time units cannot be obtained"
}

GET /bmi/models/{model}/{id}/get_time/{when}¶

Return the time of the BMI-enabled web service model with name model and id after it is initialized.

Parameters:	model (string) – the name of the model id (string) – the ID of the model instance, generated when the model is instantiated when (string) – the specified time (the available options for when are “current”, “start” and “end”)

Example request:

GET /bmi/models/met_base/fa821dfbc4844559a6d67e910aa58db5/get_time/current HTTP/1.1
Host: ecgs.ncsa.illinois.edu/

Example response1: when it succeeds in getting the current time:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "time": 12.0
}

Example response2: when it fails:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "info": "current time cannot be obtained"
}

Endpoints for Grid Control Functions¶

GET /bmi/models/{model}/{id}/{var}/get_grid_properties¶

Return the grid properties of the variable with name var in the BMI-enabled web service model with name model and id after it is initialized.

Parameters:	model (string) – the name of the model id (string) – the ID of the model instance, generated when the model is instantiated var (string) – the standard name of the variable used by the model

Example request:

GET /bmi/models/met_base/fa821dfbc4844559a6d67e910aa58db5/land_surface__slope_angle/get_grid_properties HTTP/1.1
Host: ecgs.ncsa.illinois.edu/

Example response1: when it succeeds:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "grid_type": "uniform",
  "grid_info": {
    "lower_left_corner": [377239, 4459392, 0.0],
    "spacing": [24.37, 32.85, 0.0],
    "shape": [586, 399, 0]
  }
}

Example response2: when it fails:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "info": "fail in getting the grid properties of land_surface__slope_angle."
}

Endpoints for Variable Setter Functions¶

PUT /bmi/models/{model}/{id}/set_vars_provided_list¶

Inform the BMI-enabled web service model with name model and id of the variables which would be used by other models after it is instantiated.

Request JSON Object:
Parameters:	model (string) – the name of the model id (string) – the ID of the model instance, generated when the model is instantiated
	vars_provided (list[string]) – a list of variables which would used by other models in standard names.

Example request:

PUT /bmi/models/met_base/fa821dfbc4844559a6d67e910aa58db5/set_vars_provided HTTP/1.1
Host: ecgs.ncsa.illinois.edu/
Accept: application/json
Data: {"vars_provided": ["atmosphere_aerosol_dust__reduction_of_transmittance", "atmosphere_air-column_water-vapor__liquid-equivalent_depth"]}

Example response1: when it succeeds:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "info": "success"
}

Example response2: when it fails:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "info": "Fail in setting the provided variable list."
}

PUT /bmi/models/{model}/{id}/set_values_for_vars¶

Reset the values of some variables in the BMI-enabled web service model with name model and id by sending a NetCDF file which includes the values of variables to be setted after the model is instantiated.

Form Parameters:
Parameters:	model (string) – the name of the model id (string) – the ID of the model instance, generated when the model is instantiated
	setted_vars_file – a file object containing the values of the variables that are to be setted in a NetCDF file

Example response1: when it succeeds:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "info": "success"
}

Example response2: when it fails:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "info": "Fail in setting the provided variable list."
}

Other Endpoints¶

PUT /bmi/models/{model}/{id}/send_cfg_sup_files¶

Send a configuration file along with any input files to the BMI-enabled web service model with name model and id after the model is instantiated.

Form Parameters:
Parameters:	model (string) – the name of the model id (string) – the ID of the model instance, generated when the model is instantiated
	cfg_file – a file object for the configuration file sup_file – a file object for any input file (can be more than one)

Example response1: when the configuration file(s) is successfully sent to the service:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "info": "success"
}

Example response2: when it fails:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "info": "Fail. File is not valid."
}

PUT /bmi/models/{model}/{id}/update/{mode_status}¶

Update the mode status of the BMI-enabled web service model with name model and id after it is instantiated.

Parameters:	model (string) – the name of the model id (string) – the ID of the model instance, generated when the model is instantiated mode_status (string) – the mode status of the model (options: “driver” and “nondriver”)

Example request:

PUT /bmi/models/met_base/fa821dfbc4844559a6d67e910aa58db5/update/driver HTTP/1.1
Host: ecgs.ncsa.illinois.edu/

Example response1: when it succeeds:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "mode": "driver"
}

Example response2: when it fails:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "info": "the mode is not updated"
}

GET /bmi/models/{model}/{id}/output¶

Get the information of the output files of the BMI-enabled web service model with name model and id after it is instantiated.

Parameters:	model (string) – the name of the model id (string) – the ID of the model instance, generated when the model is instantiated

Example request:

PUT /bmi/models/met_base/fa821dfbc4844559a6d67e910aa58db5/output HTTP/1.1
Host: ecgs.ncsa.illinois.edu/

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "files": ["test_0D-I.nc"]
}

GET /bmi/models/{model}/{id}/download_temp_nc/{filename}¶

Download the temporary NetCDF files of the BMI-enabled web service model with name model and id after the model is initialized, updated and finalized.

Parameters:	model (string) – the name of the model id (string) – the ID of the model instance, generated when the model is instantiated filename (string) – the filename of the temporary NetCDF files

GET /bmi/models/{model}/{id}/download_output/{filename}¶

Download the output files (if any) of the BMI-enabled web service model with name model and id after the model is finalized. The output file information can be obtained from the API endpoint of output.

Parameters:	model (string) – the name of the model id (string) – the ID of the model instance, generated when the model is instantiated filename (string) – the filename of the output file

DELETE /bmi/models/{model}/{id}/remove¶

Remove the instance (the including the model instance and the files (i.e., input, output and temp files) if any) of BMI-enabled web service model with name model and id after the model is instantiated.

Example request:

DELETE /bmi/models/met_base/fa821dfbc4844559a6d67e910aa58db5/remove HTTP/1.1
Host: ecgs.ncsa.illinois.edu/

Example response1: when the model instance is removed:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "info": "success"
}

Example response2: when the ID does not exist*:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "info": "ID does not exist"
}