# 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]

<mark style="color:green;">`POST`</mark> `https://api.olisystems.com/engine/flash/{dbs_file_id}/isothermalFlash`

&#x20;The first request to initiate an isothermal flash calculation

#### Headers

| Name          | Type   | Description            |
| ------------- | ------ | ---------------------- |
| Authorization | string | Bearer {access\_token} |
| Content-Type  | string | application/json       |

{% tabs %}
{% tab title="200 " %}

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

{% endtab %}
{% endtabs %}

### 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** |

{% hint style="warning" %}
**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](https://devdocs.olisystems.com/uploading-oli-files).
{% endhint %}

## Result of computation \[2nd request and onwards]

<mark style="color:blue;">`GET`</mark> `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       |

{% tabs %}
{% tab title="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"
}
```

{% endtab %}
{% endtabs %}

{% hint style="warning" %}
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
{% endhint %}

#### Example chain of request responses

```javascript
// 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"
}
```

{% hint style="warning" %}
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
{% endhint %}