Visuals API Overview

The Informer Visuals API provides endpoints for creating and managing visual components like charts, graphs, and dashboards. Visuals can be embedded in reports or saved as standalone components. All routes are prefixed with /api.

Features

• Chart Components - Create various chart types (bar, line, pie, etc.)
• Embedded Visuals - Embed visuals in reports or use standalone
• Multiple Formats - Export as JSON or HTML
• Component System - Flexible visual component definitions

Authentication

All Visual API endpoints require authentication via session cookies or API tokens. Creating visuals requires permission.visuals.create.

Endpoints

GET /api/visuals

Get a list of all visuals.

Authentication: Required (session)

Response:

{
  "_links": {
    "self": { "href": "/api/visuals" }
  },
  "_embedded": {
    "inf:visual": [
      {
        "id": "visual-123",
        "name": "Sales Chart",
        "description": "Monthly sales bar chart",
        "component": {
          "type": "chart",
          "chartType": "bar",
          "data": {},
          "options": {}
        },
        "embedded": false,
        "ownerId": "john",
        "createdAt": "2024-01-15T10:30:00Z",
        "updatedAt": "2024-01-15T10:30:00Z",
        "_links": {
          "self": { "href": "/api/visuals/visual-123" }
        }
      }
    ]
  },
  "start": 0,
  "count": 1,
  "total": 1
}

---

POST /api/visuals

Create a new visual component.

Authentication: Required (session)

Pre-blocks: permission.visuals.create

Request Body:

Field	Type	Required	Description
component	object	Yes	Visual component definition
name	string	No	Visual name (null allowed)
description	string	No	Visual description (null or empty allowed)
embedded	boolean	No	Embedded in another entity (default: false)

Component Object:

Field	Type	Description
type	string	Component type (chart, table, etc.)
chartType	string	Chart type (bar, line, pie, etc.)
data	object	Chart data configuration
options	object	Chart display options

Example Request:

{
  "name": "Quarterly Revenue",
  "description": "Revenue by quarter",
  "component": {
    "type": "chart",
    "chartType": "bar",
    "data": {
      "labels": ["Q1", "Q2", "Q3", "Q4"],
      "datasets": [
        {
          "label": "Revenue",
          "data": [100000, 125000, 150000, 175000]
        }
      ]
    },
    "options": {
      "responsive": true,
      "title": {
        "display": true,
        "text": "Quarterly Revenue"
      }
    }
  },
  "embedded": false
}

Response:

Returns the created visual object with 201 Created status and Location header.

{
  "id": "visual-456",
  "name": "Quarterly Revenue",
  "description": "Revenue by quarter",
  "component": {
    "type": "chart",
    "chartType": "bar",
    "data": { },
    "options": { }
  },
  "embedded": false,
  "ownerId": "john",
  "createdAt": "2024-01-15T14:22:00Z",
  "updatedAt": "2024-01-15T14:22:00Z"
}

---

GET /api/visuals/{id}

Get a specific visual by ID.

Authentication: Required (session)

Pre-blocks: visual.lookup(params.id)

Response:

{
  "id": "visual-123",
  "name": "Sales Chart",
  "description": "Monthly sales bar chart",
  "component": {
    "type": "chart",
    "chartType": "bar",
    "data": {
      "labels": ["Jan", "Feb", "Mar"],
      "datasets": [
        {
          "label": "Sales",
          "data": [12000, 15000, 18000]
        }
      ]
    },
    "options": {
      "responsive": true
    }
  },
  "embedded": false,
  "ownerId": "john",
  "createdAt": "2024-01-15T10:30:00Z",
  "updatedAt": "2024-01-15T10:30:00Z",
  "_links": {
    "self": { "href": "/api/visuals/visual-123" }
  }
}

---

PUT /api/visuals/{id}

Update a visual.

Authentication: Required (session)

Pre-blocks: visual.lookup(params.id), permission.visual.write(pre.visual)

Request Body:

Field	Type	Description
name	string	Visual name
description	string	Visual description
component	object	Visual component definition
embedded	boolean	Embedded status

Example Request:

{
  "name": "Updated Sales Chart",
  "component": {
    "type": "chart",
    "chartType": "line",
    "data": {
      "labels": ["Jan", "Feb", "Mar", "Apr"],
      "datasets": [
        {
          "label": "Sales",
          "data": [12000, 15000, 18000, 20000]
        }
      ]
    }
  }
}

Response:

Returns the updated visual object.

---

DELETE /api/visuals/{id}

Delete a visual.

Authentication: Required (session)

Pre-blocks: visual.lookup(params.id), permission.visual.write(pre.visual)

Response:

Returns 204 No Content on successful deletion.

---

GET /api/visuals/{id}/component.{ext}

Get visual component in specified format.

Authentication: Required (session)

Path Parameters:

Parameter	Type	Description
id	string	Visual ID
ext	string	Format: json, html (default: json)

Query Parameters:

Parameter	Type	Description
download	boolean	Force download with filename

Example Requests:

GET /api/visuals/visual-123/component.json
GET /api/visuals/visual-123/component.html
GET /api/visuals/visual-123/component.html?download=true

Response (JSON format):

Returns the component object:

{
  "type": "chart",
  "chartType": "bar",
  "data": {
    "labels": ["Jan", "Feb", "Mar"],
    "datasets": [
      {
        "label": "Sales",
        "data": [12000, 15000, 18000]
      }
    ]
  },
  "options": {
    "responsive": true
  }
}

Response (HTML format):

Returns rendered HTML visualization with appropriate Content-Type: text/html header.

---

Chart Types

Supported chart types in component definitions:

• bar - Vertical bar chart
• horizontalBar - Horizontal bar chart
• line - Line chart
• pie - Pie chart
• doughnut - Doughnut chart
• radar - Radar chart
• polarArea - Polar area chart
• bubble - Bubble chart
• scatter - Scatter plot

Component Structure

Basic component structure:

{
  "type": "chart",
  "chartType": "bar",
  "data": {
    "labels": ["Label 1", "Label 2"],
    "datasets": [
      {
        "label": "Dataset 1",
        "data": [10, 20],
        "backgroundColor": "#4CAF50"
      }
    ]
  },
  "options": {
    "responsive": true,
    "maintainAspectRatio": false,
    "title": {
      "display": true,
      "text": "Chart Title"
    },
    "legend": {
      "display": true,
      "position": "bottom"
    }
  }
}

Embedded vs Standalone

• Embedded visuals - Used within reports or dashboards, not listed in visual library
• Standalone visuals - Saved in visual library, can be reused across reports

Use Cases

Sales Dashboard

{
  "name": "Sales Dashboard",
  "component": {
    "type": "chart",
    "chartType": "line",
    "data": {
      "labels": ["Jan", "Feb", "Mar", "Apr", "May", "Jun"],
      "datasets": [
        {
          "label": "Revenue",
          "data": [45000, 52000, 48000, 61000, 58000, 67000],
          "borderColor": "#4CAF50",
          "fill": false
        }
      ]
    }
  }
}

Product Comparison

{
  "name": "Product Comparison",
  "component": {
    "type": "chart",
    "chartType": "radar",
    "data": {
      "labels": ["Quality", "Price", "Performance", "Support", "Features"],
      "datasets": [
        {
          "label": "Product A",
          "data": [80, 70, 85, 90, 75]
        },
        {
          "label": "Product B",
          "data": [70, 90, 75, 80, 85]
        }
      ]
    }
  }
}