Skip to main content

JSON datasource

JSON datasources allow you to fetch and display data from JSON APIs, REST endpoints, or any URL that returns JSON formatted data. The system automatically parses JSON structures and makes the data available to your widgets and templates.

Prerequisites​

Before creating a JSON datasource, ensure you have:

  • A valid JSON API endpoint or URL that returns JSON data
  • Proper network access to the JSON source
  • Understanding of the JSON structure you want to consume
  • Authentication credentials if required by the API

Supported JSON Structures​

The JSON datasource supports various data structures:

Simple Object:

{
  "title": "Weather Update",
  "temperature": "25°C",
  "condition": "Sunny"
}

Array of Objects:

[
  {
    "name": "Product 1",
    "price": "$19.99",
    "stock": 15
  },
  {
    "name": "Product 2",
    "price": "$29.99",
    "stock": 8
  }
]

Nested Structure:

{
  "data": {
    "items": [
      {
        "id": 1,
        "details": {
          "name": "Item 1",
          "category": "Electronics"
        }
      }
    ],
    "metadata": {
      "total": 1,
      "updated": "2024-01-15T10:30:00Z"
    }
  }
}

Create datasource​

Go to Datasources > Click Add new in the External datasource tab > Choose the JSON type.

Basic Configuration​

1. Update Schedule Decide how your datasource updates from the original source:

  • Select a Refresh Frequency for regular intervals (every minute, hour, day, etc.)
  • Specify a Cron Expression for custom scheduling
Example Cron Expressions
  • 0 */5 * * * * - Every 5 minutes
  • 0 0 */1 * * * - Every hour
  • 0 0 9 * * * - Daily at 9:00 AM
JSON Refreshing

For more information about external datasource refresh options, see the External Datasource Refreshing documentation.

2. JSON Endpoint URL In the URL field, enter the JSON API endpoint or URL. The URL must:

  • Return valid JSON content
  • Be accessible from your server
  • Use HTTP or HTTPS protocol
Valid JSON URL Examples
  • https://api.example.com/data.json
  • https://jsonplaceholder.typicode.com/posts
  • https://api.openweathermap.org/data/2.5/weather?q=London&appid=YOUR_API_KEY

Advanced Configuration Options​

3. Datasource Settings Configure datasource behavior:

  • Active: Enable/disable the datasource without deleting it
  • Ignore Error counter: Continue operation even if errors occur during data fetching

4. Editor Settings Configure how the system processes JSON data:

  • Cache external resources: Store external content (images, files) referenced in JSON locally for faster access
  • Remove broken external resource references: Automatically clean up invalid links found in JSON data
  • Rotate cache on every update: Clear and rebuild cache with each data refresh to ensure fresh content
  • Exchange internal resource references: Update internal file paths when content is moved or reorganized
  • Request settings: Configure HTTP headers, authentication, timeout, and other request parameters

5. Array Processing Enable Randomize arrays to shuffle the order of array elements each time the datasource updates. This is useful for:

  • Rotating through different content items
  • Displaying varied information on each refresh
  • Creating dynamic content presentation

Request Settings Configuration​

For APIs requiring authentication or special headers:

  1. Click on Request settings to expand advanced options
  2. Configure authentication methods:
    • Basic Auth: Username and password
    • Bearer Token: API tokens or JWT
    • Custom Headers: API keys, content types, etc.
  3. Set request timeout and retry options
  4. Configure SSL/TLS settings if needed
API Authentication Example

For APIs requiring an API key in the header:

  • Header Name: X-API-Key
  • Header Value: your-api-key-here

6. Save Configuration Once all settings are configured according to your JSON source requirements, click Save to create the datasource.

Using JSON Data in Widgets​

After creating the JSON datasource, you can bind the data to widgets using dot notation:

  • Simple values: data.title, data.temperature
  • Array elements: data.items[0].name, data.items[1].price
  • Nested objects: data.metadata.total, data.details.category

Common JSON API Types​

REST APIs: Standard HTTP APIs returning JSON responses
Weather APIs: Current conditions, forecasts, alerts
News APIs: Headlines, articles, RSS-to-JSON services
Social Media APIs: Posts, feeds, statistics
E-commerce APIs: Product catalogs, inventory, pricing
Custom Applications: Internal systems, databases via API