Use the Plotly Images REST Service Endpoint

Last modified: November 19, 2024

Introduction

The Plotly API images endpoint turns a plot into an image of the desired format. A set of body parameters and headers are passed to the endpoint, which returns an image when a request is made.

This how-to teaches you how to do the following:

Call Plotly API Images’ REST Endpoint
Save images returned from generated by the endpoint

Prerequisites

Before starting this how-to, make sure you have completed the following prerequisites:

Create an account on plot.ly: you can sign up to plot.ly here: Plotly Sign Up
Retrieve the plotly API key which goes with your account; your API key can be found on the settings page when you are logged in to the site

Setting up the Domain Model

To set up the domain model for use with the plotly REST service endpoint, follow these steps:

Create two entities: Image and DataSource.
Image should be a specialization of the System.Image entity, so set Generalization to System.Image.
DataSource should be non-persistable with Data and Layout string attributes.

Calling the ‘Plotly API Images’ REST Endpoint

To make a call to Plotly API images REST endpoint, follow these steps:

Add a blank page to the existing module.
Add a Data view with data source as a microflow that returns a new DataSource object.
In the Data view, place input elements with source attribute as Data and Layout.
In the footer of the Data view, add a Call microflow button.
Link the button to a new microflow: ACT_Call_REST.
Rename the button Call Plotly REST Service.
Right click the button, select to Go to on click microflow….
Build the microflow as shown below.
The Call REST service activity is configured as follows:
- In the tab General, the Location should be set to https://api.plot.ly/v2/images
- Select the HTTP Method as POST
- In the tab HTTP Headers, Enter your plotly user name and API key (more information on plotly authentication can be found here: plotly Authentication)
  
  Custom HTTP headers ‘Content-Type’ and ‘Plotly-Client-Platform’ must be provided
- In the tab Request, select Custom request template; the request is a ‘JSON’ object with the structure
```
{
    "figure": {
        "data": [{"y": [10, 10, 2, 20]}],
        "layout": {"width": 700}
    },
    "format": "png",
    "encoded": false
}
```
  For more request parameter details, see the documentation here: Plotly REST API, v2.
  
  When encoded is set to true, a base64 image url is returned.
  
  In the field Template, escape the opening brace, {, by using a double opening brace, {{.
- In the tab Response, set Response handling to Store in a file document
- Set Output > Type to the Image entity

Saving the Image

To save images generated by the REST service, follow these steps:

Add a Show page activity to the ACT_Call_REST microflow.
Select a new page.
Set the generated image object as the Object to pass to the page.
Set the layout of the page as a popup.
Place a Data view in the page and populate it as shown below:
Run the app.
In the browser, open the page with the Call Plotly REST Service button.
Fill in the Data and Layout fields. An example is shown in the image below.
Click the Call Plotly REST Service button.
Click the Save button to save the image which is displayed.