API Integration Checklist

To ensure a smooth and successful API integration, we recommend using the following checklist as a reference guide for building an API integration with WISEflow.

Call Sequence

When calling endpoints in a sequence, one of the calls in the sequence might fail and be subject to a retry. If this happens, the sequence should be stopped at the point of failure. 

Example:

A call sequence:

1. Call A, success
2. Call B, fails
3. Call C

Whenever a call fails, the rest of the sequence will not work as intended, the rest of the sequence should be omitted, and appropriate error handling takes place. 

Exponential Backoff Retry

Exponential backoff retry is a way to manage retries in a responsible and structured way. It works by waiting progressively longer between each retry request. This approach is less load-heavy on the API and will provide a better, more stable API. The WISEflow API will respond with an 429 error if there are too many requests to the API.

Example:

Exponential backoff retries request exponentially:

1. If the request fails, wait 2 seconds before the next retry
2. If the request fails, wait 4 seconds before the next retry
3. If the request fails, wait 8 seconds before the next retry
4. …
5. …

exponentialBackoff = interval * multiplier^n

where

• interval is the initial interval for the first retry
• n is the number of failures that have occurred
• the multiplier is the multiplier for the retry

While waiting progressively longer between each retry, the retries are however still synchronised.

Add Jitter to the Exponential Backoff Retry

Adding jitter to the exponential backoff adds some randomness to the retry calls that will break the synchronisation:

1. If the request fails, wait 2 seconds + random interval before the next retry
2. If the request fails, wait 4 seconds + random interval before the next retry
3. If the request fails, wait 8 seconds + random interval before the next retry
4. …
5. …

exponentialBackoff = interval * multiplier^n +/- jitter

where

• interval is the initial interval for the first retry
• n is the number of failures that have occurred
• the multiplier is the multiplier for the retry
• jitter is added or subtracted to break synchronisation

Now each retry call will be spread over a random period within a set interval.

Monitoring and Error Logging

To ease error handling, API calls and data should be monitored and logged. As a minimum, we recommend that the request and response details (such as method, URL, headers, body, status, etc.) are logged. Logging exceptions and errors will also make it easier to provide technical support to resolve any issues.

Log the Trace Id

Each response from the WISEflow API includes an “X-Trace-Id”. The trace Id is a unique way of identifying and tracking what exactly is happening with a request. Logging the trace Id is a useful way to diagnose unexpected or undesirable behaviour.

Add an Institution Specific Header

Adding an “X-Client-Name” to the header when making calls to the API will make error handling and diagnostics easier. The “X-Client-Name” should be easily recognisable, e.g., University of WISEflow.