API Mini Guide

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

1. 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.
2. After the chart is refreshed, make a GET call to the Get Chart Screenshot endpoint.
3. 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 to false to validate if the dashboard is a draft.
• Check if there are any elements in the position_json (text elements are declared as MARKDOWN-{{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 and certified_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:

• For dashboards
• For charts

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:

1. 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}}).
2. The response includes a json_metadata value, which is a string that can be loaded as a JSON.
3. Get the value for the native_filter_configuration key, from the json_metadata JSON.
4. The native_filter_configuration key includes the configuration for all filters. We're specifically looking for:
   1. The id.
   2. The defaultDataMask configuration.
5. 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": []
}

6. Use this payload in the Create a Permalink to a Dashboard endpoint.