Use the Plotly Images REST Service Endpoint

Last modified: October 12, 2023

1 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

2 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: https://plot.ly/accounts/login/?action=signup#/
  • 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

3 Setting up the Domain Model

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

  1. Create two entities: Image and DataSource.

  2. Image should be a specialization of the System.Image entity, so set Generalization to System.Image.

    image entity
  3. DataSource should be non-persistable with Data and Layout string attributes.

    DataSource entity

4 Calling the ‘Plotly API Images’ REST Endpoint

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

  1. Add a blank page to the existing module.

  2. Add a Data view with data source as a microflow that returns a new DataSource object.

  3. In the Data view, place input widgets with source attribute as Data and Layout.

    Data view
  4. In the footer of the Data view, add a Call microflow button.

  5. Link the button to a new microflow: ACT_Call_REST.

  6. Rename the button Call Plotly REST Service.

    Configured microflow
  7. Right click the button, select to Go to on click microflow….

  8. Build the microflow as shown below.

    Configured microflow
  9. 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

      Location
    • Select the HTTP Method as POST

      HTTP Method
    • In the tab HTTP Headers, Enter your plotly user name and API key (more information on plotly authentication can be found here: https://api.plot.ly/v2/#authentication)

      Authorization
    • In the tab Request, select Custom request template; the request is a ‘JSON’ object with the structure

      1
      2
      3
      4
      5
      6
      7
      8
      
      {
          "figure": {
              "data": [{"y": [10, 10, 2, 20]}],
              "layout": {"width": 700}
          },
          "format": "png",
          "encoded": false
      }
      
      Request tab

      For more request parameter details, see the documentation here: Plotly REST API, v2.

    • In the tab Response, set Response handling to Store in a file document

      Response tab
    • Set Output > Type to the Image entity

5 Saving the Image

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

  1. Add a Show page activity to the ACT_Call_REST microflow.

  2. Select a new page.

  3. Set the generated image object as the Object to pass to the page.

  4. Set the layout of the page as a popup.

  5. Place a Data view in the page and populate it as shown below:

    Display image page
  6. Run the app.

  7. In the browser, open the page with the Call Plotly REST Service button.

  8. Fill in the Data and Layout fields. An example is shown in the image below.

    Fill in data
  9. Click the Call Plotly REST Service button.

    Save image
  10. Click the Save button to save the image which is displayed.

6 Read More