API Reference

Overview

Data Lens provides a RESTful API for programmatic access to custom reports. The API respects all security configurations including multi-tenancy, authentication, and IP whitelisting.

Base URL

https://your-app.com/api/data-lens

Note: The API path can be customized per panel using ->apiPath(). See Configuration for details.

Authentication

Data Lens supports multiple authentication methods:

API Key Authentication

Generate an API key for a report through the UI and include it in the request:

# Using X-API-Key header (recommended)
curl -H "X-API-Key: YOUR_API_KEY" \
     "https://your-app.com/api/data-lens/reports/{uuid}/data"

# Using query parameter (legacy)
curl "https://your-app.com/api/data-lens/reports/{uuid}/data?api_key=YOUR_API_KEY"

Note: The X-API-Key header takes precedence over the query parameter when both are present.

Laravel Sanctum

Use your existing Sanctum tokens:

curl -H "Authorization: Bearer YOUR_SANCTUM_TOKEN" \
     "https://your-app.com/api/data-lens/reports/{uuid}/data"

No Authentication

For public reports (when explicitly enabled):

curl "https://your-app.com/api/data-lens/reports/{uuid}/data"

IP Whitelisting

When configured, the API only accepts requests from whitelisted IPs:

// Configure IP whitelisting globally in config/data-lens.php
'api' => [
    'ip_whitelist' => [
        '192.168.1.0/24',  // CIDR notation
        '10.0.0.50',       // Single IP
    ],
],

Behavior:

null or [] - Allow all IPs (no restrictions)
Array with IPs - Only listed IPs can access (non-whitelisted IPs receive 403 Forbidden)

Endpoints

Get Report Metadata

Retrieve report configuration and metadata.

GET /api/data-lens/reports/{uuid}

Parameters:

uuid - The report's API UUID (found in report settings)

Response:

{
    "data": {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "name": "Sales Report",
        "created_at": "2024-01-15T10:00:00Z",
        "updated_at": "2024-01-15T10:00:00Z",
        "columns": [
            {
                "name": "order_date",
                "label": "Order Date",
                "type": "date"
            },
            {
                "name": "total_revenue",
                "label": "Total Revenue",
                "type": "money"
            }
        ]
    }
}

Get Report Data

Retrieve paginated report data.

GET /api/data-lens/reports/{uuid}/data

Parameters:

uuid - The report's API UUID
page - Page number (optional, default: 1)
per_page - Records per page (optional, default: 50, max: 1000)

Response:

{
    "data": [
        {
            "order_date": "2024-01-15",
            "total_revenue": 1500.50,
            "customer_name": "Acme Corp",
            "status": "completed"
        },
        {
            "order_date": "2024-01-14",
            "total_revenue": 2300.00,
            "customer_name": "Tech Solutions",
            "status": "completed"
        }
    ],
    "links": {
        "first": "https://your-app.com/api/data-lens/reports/{uuid}/data?page=1",
        "last": "https://your-app.com/api/data-lens/reports/{uuid}/data?page=10",
        "prev": null,
        "next": "https://your-app.com/api/data-lens/reports/{uuid}/data?page=2"
    },
    "meta": {
        "current_page": 1,
        "from": 1,
        "last_page": 10,
        "links": [
            {
                "url": null,
                "label": "&laquo; Previous",
                "active": false
            },
            {
                "url": "https://your-app.com/api/data-lens/reports/{uuid}/data?page=1",
                "label": "1",
                "active": true
            },
            {
                "url": "https://your-app.com/api/data-lens/reports/{uuid}/data?page=2",
                "label": "2",
                "active": false
            }
        ],
        "path": "https://your-app.com/api/data-lens/reports/{uuid}/data",
        "per_page": 50,
        "to": 50,
        "total": 500
    }
}

Response Formats

Successful Responses

All successful responses use standard HTTP status codes:

200 OK - Request completed successfully

Error Responses

Error responses include a consistent error structure:

{
    "message": "The given data was invalid.",
    "errors": {
        "per_page": [
            "The per page may not be greater than 1000."
        ]
    }
}

Common Error Codes:

401 Unauthorized - Missing or invalid authentication
403 Forbidden - IP not whitelisted or insufficient permissions
404 Not Found - Report not found or API not enabled for report
422 Unprocessable Entity - Validation errors
429 Too Many Requests - Rate limit exceeded
500 Internal Server Error - Server error

Pagination

The API uses Laravel's standard pagination format with the following metadata:

current_page - Current page number
from - First record number on current page
to - Last record number on current page
last_page - Total number of pages
per_page - Records per page
total - Total number of records

Pagination Examples

# Get first page with default per_page (50)
GET /api/data-lens/reports/{uuid}/data

# Get specific page
GET /api/data-lens/reports/{uuid}/data?page=3

# Custom page size
GET /api/data-lens/reports/{uuid}/data?per_page=100

# Combine pagination parameters
GET /api/data-lens/reports/{uuid}/data?page=2&per_page=25

Rate Limiting

API requests are subject to your application's rate limiting configuration. Default Laravel rate limiting applies unless customized.

Multi-Tenancy

For tenant-aware installations:

API automatically scopes data to the authenticated user's tenant
Cross-tenant data access is prevented
Tenant context is maintained in all queries

Validation Rules

Report UUID

Must be a valid UUID v4 format
Example: 550e8400-e29b-41d4-a716-446655440000

Pagination Parameters

page: Integer, minimum 1
per_page: Integer, minimum 1, maximum 1000

Code Examples

# Get report data with API key
curl "https://your-app.com/api/data-lens/reports/{uuid}/data?api_key=YOUR_API_KEY"

# With pagination
curl "https://your-app.com/api/data-lens/reports/{uuid}/data?api_key=YOUR_API_KEY&page=2&per_page=100"

# Using Bearer token
curl -H "Authorization: Bearer YOUR_TOKEN" \
     "https://your-app.com/api/data-lens/reports/{uuid}/data"

Best Practices

Cache API Responses: Report data can be cached on your end to reduce API calls
Use Appropriate Page Sizes: Balance between number of requests and response size
Handle Pagination: Always check for additional pages of data
Error Handling: Implement proper error handling for all possible response codes
Respect Rate Limits: Implement backoff strategies for rate limit errors

Documents