API call blueprint

The time to run a calculation using the OLI API cannot be predicted accurately and also some calculations may take longer to compute than others. Hence, a polling mechanism is required to retrieve the result of each calculation. The steps for this mechanism is described below.

1. Send a GET/POST request to the specific URL

2. If the request was successful(status:200), the JSON response back will contain a link to the results and status of the computation. The status can be IN QUEUE/IN PROGRESS

3. Keep polling the results link with a GET request until status of the response changes to PROCESSED/FAILED/ERROR

4. if status is PROCESSED, then response will also contain the result of the computation

Here is an example for an isothermal flash call

Isothermal flash [1st request]

POST https://api.olisystems.com/engine/flash/{dbs_file_id}/isothermalFlash

The first request to initiate an isothermal flash calculation

Headers

Name	Type	Description
Authorization	string	Bearer {access_token}
Content-Type	string	application/json

200

{
	"code": 200,
	"data": {
		"file_id": "dee854a6-59db-487d-ad08-a20dee691133",
		"jobId": "f6b3375e-cd0f-4ace-a5ee-71e047b76754",
		"resultsLink": "https://devapi.olisystems.com/result/flash/f6b3375e-cd0f-4ace-a5ee-71e047b76754?context=engine",
		"status": "IN PROGRESS"
	},
	"message": "Process execution started Successfully",
	"status": "SUCCESS"
}

Response description

field	description
code	HTTP response status code
data.file_id	the dbs file reference identifier
data.jobId	the current request job identifier
data.resultsLink	the https endpoint to poll to get the final result
data.status	current status of the job
message	message describing the request
status	status of the current request, can be SUCCESS or FAILED

access_token in the request authorization header is obtained as shown here.

db_file_id is the id of the dbs file, you can obtain it here.

Result of computation [2nd request and onwards]

GET https://api.olisystems.com/result/flash/{jobId}?context=engine

URL contains the result of the computation if status is processed

Headers

Name	Type	Description
Authorization	string	Bearer {access_token}
Content-Type	string	application/json

200

{
    "code": 200, 
    "data": {
        "result": {
          ...
          }
    }, 
    "message": "Results returned successfully", 
    "resultsLink": "https://devapi.olisystems.com/result/flash/fbce59ee-f31e-447b-b450-ba5b0d0a1a99?context=engine", 
    "status": "PROCESSED"
}

status can be IN QUEUE, IN PROGRESS, PROCESSED, FAILED or ERROR

if status = IN QUEUE/IN PROGRESS, keep polling the endpoint in resultsLink

if status = PROCESSED, result should be in data.result

if status = FAILED, computation failure. error will be be in data.error

if status = ERROR, a system error occurred

Example chain of request responses

// 1st Response
{
  "code": 200, 
  "data": {
    "fileId": "b60c97de-3486-4165-8589-d9885d14a382", 
    "jobId": "318e35c7-609b-466f-876f-e872a5b0a4a0", 
    "resultsLink": "https://api.olisystems.com/result/flash/318e35c7-609b-466f-876f-e872a5b0a4a0?context=engine", 
    "status": "IN PROGRESS"
  }, 
  "message": "Process execution started Successfully", 
  "status": "SUCCESS"
}

// 2nd response on GET resultsLink
{
  "code": 200, 
  "data": {}, 
  "message": "Results returned successfully", 
  "resultsLink": "https://api.olisystems.com/result/flash/318e35c7-609b-466f-876f-e872a5b0a4a0?context=engine", 
  "status": "IN PROGRESS"
}

// 3rd request on GET resultsLink (still in progress)
{
  "code": 200, 
  "data": {}, 
  "message": "Results returned successfully", 
  "resultsLink": "https://api.olisystems.com/result/flash/318e35c7-609b-466f-876f-e872a5b0a4a0?context=engine", 
  "status": "IN PROGRESS"
}

// 4th request on GET resultsLink (processed!), result in data.result
{
  "code": 200, 
  "data": {
    "result": {
      ...
      }
    },
  "message": "Results returned successfully",
  "status": "PROCESSED"
}

Presence of the data.result object signifies that results are available. if data.error object is present, then this means that the computation has failed