Asynchronous processing and polling

This section outlines how to handle long running API requests, which might otherwise time out if processed synchronously.

What is asynchronous processing?

Large or complex requests may take long to process. If processed synchronously, such requests can result in a timeout error. To avoid this issue, any request that you anticipate taking longer than about 60 seconds should be made asynchronously.

Making an asynchronous request

When you make an asynchronous API call for a long running operation, the system immediately returns a response containing only a single key: request_id. This indicates that your request has been accepted for processing without waiting for the entire operation to complete.

PAYLOAD='{
    "execution_mode": "async",
    "calculation_type": "margins",
    "currency_code": "USD",
    "cme_symbology": "clearing",
    "vendor_symbology": "clearing",
    "portfolio": [
      {
        "account_code": "Test",
        "exchange_code": "ICE.EU",
        "contract_code": "B",
        "contract_type": "FUT",
        "contract_expiry": "202705",
        "net_position": "100",
        "account_type": "H"
      }
    ]
}'

ACCESS_TOKEN='eyJraWQiOiJ3RGk0U...'
REQUEST_ID=$(curl -sSX POST "$C9_API_ENDPOINT/portfolios" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d "$PAYLOAD" | jq -r .request_id)

echo $REQUEST_ID

Polling for the result

After receiving a request_id, you will need to poll for the final result of your request. Polling is simply making additional API calls at intervals to check whether the processing is complete.

How it works:

1. Initial request: Submit your large request asynchronously and receive a request_id in response.
2. Polling requests: Use this request_id in subsequent polling API calls to query the status of your original request.
3. Final outcome: Once processing is complete, the polling request will return the complete result.

curl -sSX GET "$C9_API_ENDPOINT/results?request_id=$REQUEST_ID" \
    -H "Authorization: Bearer $ACCESS_TOKEN"

Recommendations

• Use asynchronous requests for any operation you expect to take over 60 seconds.
• Implement a polling mechanism in your client application, using the request_id from the asynchronous request to check the status until the final result is ready.
• This approach ensures that your application remains responsive even when processing large requests and avoids timeout errors.