Skip to content

API

Asynchronous API description

The simulation time of the scenarios strongly depends on the specific parameters. The simulation can take in extreme cases several minutes. The API of migraSIM is therefore implemented as a asynchronous long polling API.

summary

  1. Initiate a request: POST /request with the required parameters to start a new request. Store the returned job_id.
  2. Check request status: POST /status with the job_id to check if the request is still in progress or completed.
  3. Retrieve results: POST /results with the job_id to retrieve the results once the request is completed.

Endpoints Asynchronous API

To use the API of migraSIM the following endpoint are available:

sending request

  • URL: api/v1/asynchronous/request
  • Method: POST
  • Description: Initiates a new request.
  • Parameters:
    • data: JSON object containing the description of the scenario to simulate.
  • Response:
    • Success: The response will be a JSON object with the key "scenario" and a UUID for job ID as the value, the object is called job_id
    • Error: JSON object with an error message.

The response can be used to check the status of the request or retrieve the results. example of response:

job_id
 {"scenario": "ffa2619a-4336-4d82-809e-059968fde85c"}

example of error:

{"migraSIM error": "Content-type has to be 'application/json'."}

checking status

  • URL: api/v1/asynchronous/status
  • Method: POST
  • Description: Checks the status of a running request.
  • Parameters:
    • data: the job_id, for which the status should be checked.
  • Response:
    • Success: JSON object with status information.
    • Error: JSON object with an error message.

example of returns:

{"status": ["waiting" | "running" | "finished"], "complete": [integer]}

"complete" shows the progress in percent. The status 

{"status": "running", "complete": 100}

is not sufficient, to get the results. The simulation is complete, but there is some post-processing. So please wait for

{"status": "finished", "complete": 100}

Now the results are ready.

fecthing results

  • URL: api/v1/asynchronous/result
  • Method: POST
  • Description: Retrieves the result of a completed request.
  • Parameters:
    • data: the job_id, for which the results should be collected.
  • Response:
    • Success: JSON object with the results.
    • Error: JSON object with an error message.

sketch of the response:

{"scenario": {
                "bisphenol A": {
                                  "log": "...",
                                  "mass deviation": {"value": -1.8e-06, "unit": "%"},
                                  "mass fraction profile": [comma separated values],
                                  "migration mass": [comma separated values],
                                  "migration mass at change cycle": [comma separated values]
                                }
              },
 "config_expanded": {...},
 "creation time": "2023-06-17T09:26:00+0100",
 "credits used": 1}