API proposal for create_dashboard() and update_dashboard()

Starting a discussion for a wrapper proposal for V2 dashboard creating and updating:

https://api.plot.ly/v2/dashboards#create

I’m not aware of any formal dashboard JSON spec documentation, but this dashboard is almost exhaustive in its options usage:

https://plot.ly/dashboard/jackluo:430/view JSON: https://plot.ly/dashboard/jackluo:430/view.json

The only thing that it is missing is a table (an embedded plotly grid), which this dashboard has:

https://plot.ly/dashboard/jackp:16818 https://plot.ly/dashboard/jackp:16818.json

All of the options for styling embedded plotly grids (through URL query parameters) are here: http://help.plot.ly/add-a-table-to-spectacle-editor/

Creating a dashboard

create_dashboard()

This call to create_dashboard would create the first 2 rows of this dashboard, plus a 3rd row with a table and a markdown cell:

https://plot.ly/dashboard/jackluo:430/view

# First row has 1 graph
row1 = list( dict( type='plot', url='https://plot.ly/~jackluo/400' ) )

# Second row has 2 graphs
# These dashboard cells have titles
row2 = list(
    dict( type='plot', url='https://plot.ly/~jackluo/402',
        title='Average rotor diameter by manufacturer' ), 
    dict( type='plot', url='https://plot.ly/~jackluo/404', 
        title='Number of turbines by manufacturer' ) )

markdown_text = ""## Jack Luo | Plotly\n\nDownload original dataset here:     \nhttp://www.nature.com/articles/sdata201560\n"

table = dict(
    type = 'table', 
    url = 'https://plot.ly/~datasets/2798',
    show_row_numbers = False,
    text_transform = 'uppercase',
    header_font_weight = 300,
    header_background = '%23ab63fa'
)

# Third row has 1 table and 1 text box
# All table styling options are here: http://help.plot.ly/add-a-table-to-spectacle-editor/
row3 = list(
    table,
    dict( type='text', text=markdown_text ), 
)

dashboard = dict(
    rows = list( row1, row2, row3 ),
    foreground_color = "#cccccc", 
    box_background_color = "#020202", 
    links = [ { "url": "http://www.nature.com/articles/sdata201560", 
                "title": "| Download dataset here" } ], 
    title = "US Wind Turbine Dataset", 
    box_border_color = "#020202", 
    header_foreground_color = "#cccccc", 
    header_background_color = "#151515", 
    background_color = "#151515", 
    logo_url = "https://astrogeology.usgs.gov/images/usgs_logo_main_2x.png", 
    box_header_background_color = "#020202"
)

dashboard_url = create_dashboard( dashboard )

Updating a dashboard’s top-level attributes

update_dashboard()

Rewrite a top-level attribute of the dashboard (ie something in the “settings” key of https://plot.ly/dashboard/jackluo:430/view.json)

new_links = list( 
    dict( url = "http://www.nature.com/articles/sdata201560", 
            title = "| Download dataset here" ),
    dict( url = "#", title = "Last updated " + datetime_string ) )

update = dict( links = new_links )

update_dashboard( dashboard_url, update )

Appending or updating a dashboard row

update_dashboard_row()

Update or append one row at a time by passing the row index and

new_row = list(
    dict( type='plot', url='https://plot.ly/~jackluo/423',
        title='Blade Length' ), 
    dict( type='plot', url='https://plot.ly/~jackluo/425', 
        title='Rotor Density' ) )

# Rewrite the first row of the dashboard
update_dashboard_row( new_row, 1 )

# Append a new row to the dashboard
update_dashboard_row( new_row )

cc @charleyferrari @cldougl @theengineear @Kully @thejackluo @chriddyp

This was the simplest, no-frills API that I could think of, but there are probably better ways. 👍 if you think this looks good or chime in below to suggest some alternate proposals.

📉 📊 📈 🔢 📈 📊 📉 📊 🔢

[theengineear]

We could try to share definitions amongst all of our api endpoints (and perhaps that’s the right way to go), but I’d prefer just creating a GET /v2/dashboards/schema endpoint to expose the schema we’d be validating with. For a first pass (and maybe all we need to do), is to just go ahead and return exactly what our backend says to the caller if the validation fails on our backend.

[theengineear]

I’m not aware of any formal dashboard JSON spec documentation, but this dashboard is almost exhaustive in its options usage:

"first": {
    "boxType": "plot", 
    "shareKey": null, 
    "fileId": "jackluo:402"
}

Looks like this is versioned version: 2, which is great, let’s make sure that we can bake that into the Python handling so that we future updates don’t need to become backwards incompatible.

create_dashboard()

So far, we’ve taken the approach of object-based manipulation. The idea would be do something more like:

# Instantiate a new dashboard from scratch
dashboard = Dashboard()

# Instantiate a dashboard from url
dashboard = Dashboard(https://plot.ly/dashboard/jackluo:430)

# Methods to update a dashboard (just examples, not sure on the what methods we really need)
dashboard.add_row()
dashboard.add_column()
dashboard.update_cell(row, col, update)

Dev cycles

General question, thoughts on development cycles? Dashboards take quite a while to load if you’ve got a few plots, I think that we should have an offline integration here, right? I don’t mean that we need to have an offline-mode for dashboards, but perhaps just a way to make layout updates and see a super simple preview of the expected layout when you do make the call to Plotly to update?

It’d be sweet if you could have a dashboard.manual_sync = True flag on instantiation that allows you to sync to plotly still, but it would only happen when you call dashboard.sync() or something. I just imaging having an annoying time making small tweaks to the layout on a dashboard if I have to wait for a dashboard page to load each time.

Second thought, we could also include a ?no-content flag or something on dashboards so that you can quickly iterate loading dashboard pages in your browser (or in the notebook) without needing to load Plotly and retrieve all the plots. Not sure how hard that would be, but I really question how on board folks will be if the dev cycles for pixel pushing layout boxes is super long.

Official dashboard JSON schema

We almost got there with plot-schema, perhaps we can just take the initiative and define an official JSON-schema for these dashboards? http://json-schema.org/ If we did that in streambed, we get all these amazing validation, generation tools for free in any language we choose (yay standardization --> https://pypi.python.org/pypi/jsonschema). This also assists us with versioning down the line since we just need to match versions to schemas and go from there.

^^ Note, this isn’t super hard, the schema for the dashboards is fairly simple. I feel pretty strongly about this and I’d be happy to whip one up.

^^ Also note that I’m pretty sure there is about 0 validation on what goes into a dashboard:

POST https://api.plot.ly/v2/dashboards
{
	"content": "{\"rows\": [], \"banner\": {}, \"foobar\": \"anything i want...\"}"
}

Just works for example. We can do the same thing on the backend with jsonschema as we would in the python api library…