[SIP-31] New dashboards API

[SIP] Proposal for new dashboards API

Motivation

While moving away from MVC and specifically from ModelView’s we need to create the foundations for supporting React components and plain REST API functionality. During this transition I propose we take the chance to reorganize the current API that lives on Superset class ( exposed on /superset/*).

Final goals are:

• Restructure Superset’s API.
• Create alternatives to /superset/* API endpoints, refactor the existing functionality respecting a RESTful API design.
• Prepare/Create base CRUD API endpoints that can eventually replace MVC ModelView’s and support future React components.
• Superset API is fully documented using OAS 3.X with an optional swagger UI.

FAB’s new API highlights:

• API resource protection using JWT and/or flask-login signed cookies (current authentication method). API defaults to JWT only.
• Optional CRUD RESTful API using similar class overrides as ModelViews.
• When using auto CRUD we get rich filters, ordering, pagination and i18n for free.
• Delegate base API support like handling exceptions to FAB.
• Leverage Rison style URI arguments (we can use JSON also) out of the box with optional JSON schema validation.
• You can request for exactly the fields or metadata you want.
• OpenAPI automatic spec generation for CRUD, and easy generation for BaseApi method endpoints.

Proposed Change

Migrate and create new CRUD API endpoint for dashboards. This change proposes to create the following endpoints:

New endpoint	HTTP method	Old endpoint
/api/v1/dashboard/<id>/published	POST	/superset/dashboard/<dashboard_id>/published/
/api/v1/dashboard/user_created	GET	/superset/created_dashboards/<user_id>/
/api/v1/dashboard/user_favorite	GET	/superset/fave_dashboards/<user_id>/
/api/v1/dashboard/<id>/slice	POST	/superset/add_slices/<dashboard_id>/
/api/v1/dashboard/<id>/copy	POST	/superset/copy_dash
/api/v1/dashboard/import	POST	/superset/import_dashboards
/api/v1/dashboard/<id>	PUT	MVC and old API /dashboard/*
/api/v1/dashboard/<id>	DELETE	MVC and old API /dashboard/*
/api/v1/dashboard/	POST	MVC and old API /dashboard/*
/api/v1/dashboard/_info	GET	MVC and old API /dashboard/*
/api/v1/dashboard/	GET	MVC and old API /dashboard/*
/api/v1/dashboard/<id>	GET	MVC and old API /dashboard/*
/api/v1/dashboard/export	GET	MVC action

Endpoint description:

New endpoint	HTTP method	Description
/api/v1/dashboard/<id>/published	POST	Updates the published status of a dashboard
/api/v1/dashboard/user_created	GET	Returns current user created dashboards
/api/v1/dashboard/user_favorite	GET	Returns current user favorite dashboards
/api/v1/dashboard/<id>/slice	POST	Adds slices to a dashboard
/api/v1/dashboard/<id>/copy	POST	Copies a dashboard
/api/v1/dashboard/import	POST	Imports dashboards from a JSON file/payload
/api/v1/dashboard/<id>	PUT	Update a dashboard
/api/v1/dashboard/<id>	DELETE	Deletes a dashboard
/api/v1/dashboard/	POST	Add dashboard
/api/v1/dashboard/_info	GET	metadata for filters, add/edit fields, permissions
/api/v1/dashboard/	GET	get multiple dashboard items
/api/v1/dashboard/<id>	GET	get detail data for a dashboard
/api/v1/dashboard/export	GET	Export dashboards to YAML
Notes:

• _info endpoint will may be disabled in favor of creating an additional endpoint for fetching related field values for dropdowns
• main POST, PUT endpoints will probably be custom implemented so we don’t need to add custom functionality on pre_add, pre_update hooks

New or Changed Public Interfaces

The current dashboard API endpoints located on class Superset will continue to exist but would log a deprecation warning when accessed.

List of current endpoint’s to be “migrated”:

• /superset/dashboard/<dashboard_id>/published/
• /superset/created_dashboards/<user_id>/
• /superset/fave_dashboards/<user_id>/
• /superset/fave_dashboards_by_username/<username>/ (Just deprecation warning, this endpoint is probably not used)
• /superset/add_slices/<dashboard_id>/
• /superset/copy_dash

All React/JS references to these endpoints would be migrated to the new endpoints

Migration Plan and Compatibility

This is a side by side migration, the old API would start issuing a deprecation warning with a target version for removal. Ex: “This superset API is deprecated and will be removed in version 1.0.0”

[issue-label-bot[bot]]

Issue-Label Bot is automatically applying the label #enhancement to this issue, with a confidence of 0.86. Please mark this comment with 👍 or 👎 to give our bot feedback!

Links: app homepage, dashboard and code for this bot.

[rusackas]

@dpgaspar Since this issue is closed due to inactivity, we’ll also consider the SIP/proposal process closed as well. If you want to rekindle this proposal, please re-open this Issue, and send a new [DISCUSS] thread to the dev@ mailing list. Thank you!