- 21 Jul 2023
- 3 Minutes to read
- Print
- DarkLight
API Mini Guide
- Updated on 21 Jul 2023
- 3 Minutes to read
- Print
- DarkLight
- New
This article provides a guide on how to use the Preset API for common use cases. It explains how to take a fresh chart screenshot, delete unused assets from the workspace, and control dashboard filter values with the URL. It also provides detailed instructions on how to make POST and GET calls to the Preset endpoint, as well as how to navigate through pagination when retrieving lists of IDs. Finally, it explains how to create a payload for dynamically generating permalinks through the API.
This mini guides collection focuses on common Preset API use cases.
Before you start, make sure to generate your Preset API key for authentication. You can find detailed API key management and relevant endpoint information in the Preset API documentation.
Take a Fresh Chart Screenshot
Scenario
You want to programatically get a screenshot of a Chart as up-to-date as possible - i.e., not from cache.
Steps
- Make a POST call to the Preset Refresh Chart endpoint.
Note: This might take up to a few minutes, so please wait at least 5 minutes before going to the next step. - After the chart is refreshed, make a GET call to the Get Chart Screenshot endpoint.
- This will return a screenshot of the most up to date chart.
Delete unused assets from the Workspace
Scenario
You want to maintain Workspace content, by deleting assets that aren't in use.
Steps
Get empty dashboards
First get a list of all dashboards IDs for your workspace with theGet All Dashboards from Workspace endpoint. You can find them in the response, in the field ids
. Note that this endpoint has a limit of 100 results per request, so if you have more than 100 dashboards, you need to navigate through the pagination (by changing the page
value in the endpoint).
Then iterate through each ID and call the Get Dashboard endpoint. The response contains a chart
field that displays a list of all charts belonging to this dashboard. You can isolate the empty dashboards by selecting those that have an empty list for that field.
Keep in mind that if you have dashboards with only text (for example a homepage dashboard with links to other dashboards), this isn't considered a chart, so you can be extra carefull and look for other fileds before making a decision on deleting the asset or not:
- Check if
published
is set tofalse
to validate if the dashboard is a draft. - Check if there are any elements in the
position_json
(text elements are declared asMARKDOWN-{{id}}
).
Find orphan charts (that aren't added to any dashboard)
First get a list of all charts IDs with the Get Charts endpoint. You can find them in the response, in the field ids
. Note that this endpoint has a limit of 100 results per request, so if you have more than 100 charts, you need to navigate through the pagination (by changing the page
value in the endpoint).
Then for each ID make a call to the Get Chart endpoint. The response contains a dashboards
field, which is a list of all dashboards the chart is associated with. You can isolate orphan charts by selecting those that have an empty list for this field.
If you have use-cases in which charts aren't getting added to dashboards, you can perform additional validations to the payload, such as:
- Check if the chart is certified by checking the
certification_details
andcertified_by
values.
Delete Assets
Once you have a list of charts and/or dashboards you would like to delete, you can iterate through the list of their IDs and make calls to the delete endpoints:
Control dashboard filter values with the URL (custom permalink generation)
Scenario
You have a dashboard with filters, and you want to share a link with a particular filter selection applied.
Steps
Through the UI
To generate the link from the UI, apply the desired filter selection, and then generate a permalink.
Through the API
It's possible to dynamically generate permalinks through the API, using the Create a Permalink to a Dashboard endpoint. To do so:
- This endpoint requires a payload to specify the filter configuration, so first let's retrieve the current filter configuration for the desired dashboard, using the Get a Dashboard endpoint. You can find the dashboard ID directly in its URL (
https://{WorkspaceSlug}.{WorkspaceRegion}.app.preset.io/superset/{{dashboardID}}
). - The response includes a
json_metadata
value, which is astring
that can be loaded as a JSON. - Get the value for the
native_filter_configuration
key, from thejson_metadata
JSON. - The
native_filter_configuration
key includes the configuration for all filters. We're specifically looking for:- The
id
. - The
defaultDataMask
configuration.
- The
- Use this information to create a payload with this structure:
{
"dataMask":
{
"{{FilterID}}":
{
"id": "{{FilterID}}",
"extraFormData":
{
"filters": [
{
"col": "{{Column}}",
"op": "{{Operator}}",
"val": ["{{Value}}"]
}]
},
"filterState":
{
"validateStatus": false,
"label": "{{Value}}",
"value": ["{{Value}}"]
},
"ownState":
{},
"__cache":
{
"validateStatus": false,
"label": "{{Value}}",
"value": ["{{Value}}"]
}
}
},
"urlParams": []
}
- Use this payload in the Create a Permalink to a Dashboard endpoint.