There may be some instances when you need to generate a large API report in Assurance, this article provides step-by-step instructions on how to use the new snapshot endpoint. It aims to pre-process the report in the background, and then provide a fast, up-to-date version for tools like Power BI.
In this article, you will learn about:
- Enabling the Snapshot Scheduler
- Updating the Web Data Connector Form in PowerBI
- How the New Snapshot Endpoint Works
- Important Note
Important Note: We strongly recommend that you apply at least some filters to avoid the inclusion of unnecessary data and to speed up the process of generating a report. To learn more about applying field filters please visit this guide.
Enabling the Snapshot Scheduler
For reports that are available in API, you can now select the refresh schedule from a range of available options when using the snapshot endpoint.
You can select from the available options:
- Every 1 hour (starting from midnight, at the top of the hour)
- Every 3 hours (starting from midnight, at the top of the hour)
- Every 6 hours (starting from midnight, at the top of the hour)
- Every 12 hours (starting from midnight, at the top of the hour)
- Every day (at midnight)
- Every week (at midnight on Monday)
- Every month (at midnight on the first day of the month)
Please Note: This will only work on reports that have been selected as Available in API.
Updating the Web Data Connector Form in PowerBI
The Web Data Connector form in PowerBI should be updated as below:
Step | Field | Old Values | New Values |
1 | Basic or Advanced | Advanced | Advanced |
2 | URL parts | https://api.csassurance.com/api/v1/reports/{your-report-uuid}/{your-tenant-id} |
https://api.csassurance.com/api/v2/reports/{your-report-uuid}/snapshot |
3 and 4 | HTTP request header parameters |
|
Please note: Your Tenant ID should be entered as a header parameter (not in the URL). |
Once you have updated the connector form, you’ll then need to wait for the up-to-date version of the report to be generated which can take up to 60 minutes depending on the selected schedule.
How the New Snapshot Endpoint Works
Once you have updated your PowerBI setup to point to the new snapshot endpoint, the data will be retrieved much more quickly. The only limitation is that it is not quite real-time.
The pattern described here is pretty common among API systems that are used to return large amounts of data.
You'll find a new value at the bottom of the report, which is a timestamp for cache_refreshed_at
showing what date/time the data was “fresh”.
If you want to manually refresh it, you can do so via the Snapshot schedule within the Report setting on Assurance.
Important Note
The v1
endpoint for Assurance reports is deprecated as of 1 December 2023. While it will continue to work through the new year, we strongly encourage anyone using the Assurance API reports to adopt the v2
version of the endpoint. (Just substitute 'v2' for 'v1' in the URL - everything else is identical.) The reason for this is that the v1
endpoint can hit certain internal limits when it comes to returning large amounts of data. The v2
version does not have that restriction - although, for really large datasets, we would encourage users to adopt the cache/snapshot strategy detailed in this guide.
You will notice the following changes:
- When using the
Swagger-UI
frontend, thev1
endpoint is greyed out (although still usable) - Requests to the
v1
version will now return aDeprecated
HTTP header in the API response.
Comments
0 comments
Please sign in to leave a comment.