title: Frontend API Reference sidebar_position: 1 hide_title: true

Frontend API Reference

The @apache-superset/core package provides comprehensive APIs for frontend extension development. All APIs are organized into logical namespaces for easy discovery and use.

Core API

The core namespace provides fundamental extension functionality.

registerView

Registers a new view or panel in the specified contribution point.

core.registerView(
  id: string,
  component: React.ComponentType
): Disposable

Example:

const panel = context.core.registerView('my-extension.panel', () => (
  <MyPanelComponent />
));

getActiveView

Gets the currently active view in a contribution area.

core.getActiveView(area: string): View | undefined

Commands API

Manages command registration and execution.

registerCommand

Registers a new command that can be triggered by menus, shortcuts, or programmatically.

commands.registerCommand(
  id: string,
  handler: CommandHandler
): Disposable

interface CommandHandler {
  title: string;
  icon?: string;
  execute: (...args: any[]) => any;
  isEnabled?: (...args: any[]) => boolean;
}

Example:

const cmd = context.commands.registerCommand('my-extension.analyze', {
  title: 'Analyze Query',
  icon: 'BarChartOutlined',
  execute: () => {
    const query = context.sqlLab.getCurrentQuery();
    // Perform analysis
  },
  isEnabled: () => {
    return context.sqlLab.hasActiveEditor();
  }
});

executeCommand

Executes a registered command by ID.

commands.executeCommand(id: string, ...args: any[]): Promise<any>

SQL Lab API

Provides access to SQL Lab functionality and events.

Query Access

// Get current tab
sqlLab.getCurrentTab(): Tab | undefined

// Get all tabs
sqlLab.getTabs(): Tab[]

// Get current query
sqlLab.getCurrentQuery(): string

// Get selected text
sqlLab.getSelectedText(): string | undefined

Database Access

// Get available databases
sqlLab.getDatabases(): Database[]

// Get database by ID
sqlLab.getDatabase(id: number): Database | undefined

// Get schemas for database
sqlLab.getSchemas(databaseId: number): Promise<string[]>

// Get tables for schema
sqlLab.getTables(
  databaseId: number,
  schema: string
): Promise<Table[]>

Events

// Query execution events
sqlLab.onDidQueryRun: Event<QueryResult>
sqlLab.onDidQueryStop: Event<QueryResult>
sqlLab.onDidQueryFail: Event<QueryError>

// Editor events
sqlLab.onDidChangeEditorContent: Event<string>
sqlLab.onDidChangeSelection: Event<Selection>

// Tab events
sqlLab.onDidChangeActiveTab: Event<Tab>
sqlLab.onDidCloseTab: Event<Tab>
sqlLab.onDidChangeTabTitle: Event<{tab: Tab, title: string}>

// Panel events
sqlLab.onDidOpenPanel: Event<Panel>
sqlLab.onDidClosePanel: Event<Panel>
sqlLab.onDidChangeActivePanel: Event<Panel>

Event Usage Example:

const disposable = context.sqlLab.onDidQueryRun((result) => {
  console.log('Query executed:', result.query);
  console.log('Rows returned:', result.rowCount);
  console.log('Execution time:', result.executionTime);
});

// Remember to dispose when done
context.subscriptions.push(disposable);

Authentication API

Handles authentication and security tokens.

getCSRFToken

Gets the current CSRF token for API requests.

authentication.getCSRFToken(): Promise<string>

getCurrentUser

Gets information about the current user.

authentication.getCurrentUser(): User

interface User {
  id: number;
  username: string;
  email: string;
  roles: Role[];
  permissions: Permission[];
}

hasPermission

Checks if the current user has a specific permission.

authentication.hasPermission(permission: string): boolean

Extensions API

Manages extension lifecycle and inter-extension communication.

getExtension

Gets information about an installed extension.

extensions.getExtension(id: string): Extension | undefined

interface Extension {
  id: string;
  name: string;
  version: string;
  isActive: boolean;
  metadata: ExtensionMetadata;
}

getActiveExtensions

Gets all currently active extensions.

extensions.getActiveExtensions(): Extension[]

Events

// Extension lifecycle events
extensions.onDidActivateExtension: Event<Extension>
extensions.onDidDeactivateExtension: Event<Extension>

UI Components

Import pre-built UI components from @apache-superset/core:

import {
  Button,
  Select,
  Input,
  Table,
  Modal,
  Alert,
  Tabs,
  Card,
  Dropdown,
  Menu,
  Tooltip,
  Icon,
  // ... many more
} from '@apache-superset/core';

Example Component Usage

import { Button, Alert } from '@apache-superset/core';

function MyExtensionPanel() {
  return (
    <div>
      <Alert
        message="Extension Loaded"
        description="Your extension is ready to use"
        type="success"
      />
      <Button
        type="primary"
        onClick={() => console.log('Clicked!')}
      >
        Execute Action
      </Button>
    </div>
  );
}

Storage API

Provides persistent storage for extension data.

Local Storage

// Store data
storage.local.set(key: string, value: any): Promise<void>

// Retrieve data
storage.local.get(key: string): Promise<any>

// Remove data
storage.local.remove(key: string): Promise<void>

// Clear all extension data
storage.local.clear(): Promise<void>

Workspace Storage

Workspace storage is shared across all users for collaborative features.

storage.workspace.set(key: string, value: any): Promise<void>
storage.workspace.get(key: string): Promise<any>
storage.workspace.remove(key: string): Promise<void>

Network API

Utilities for making API calls to Superset.

fetch

Enhanced fetch with CSRF token handling.

network.fetch(url: string, options?: RequestInit): Promise<Response>

API Client

Type-safe API client for Superset endpoints.

// Get chart data
network.api.charts.get(id: number): Promise<Chart>

// Query database
network.api.sqlLab.execute(
  databaseId: number,
  query: string
): Promise<QueryResult>

// Get datasets
network.api.datasets.list(): Promise<Dataset[]>

Utility Functions

Formatting

// Format numbers
utils.formatNumber(value: number, format?: string): string

// Format dates
utils.formatDate(date: Date, format?: string): string

// Format SQL
utils.formatSQL(sql: string): string

Validation

// Validate SQL syntax
utils.validateSQL(sql: string): ValidationResult

// Check if valid database ID
utils.isValidDatabaseId(id: any): boolean

TypeScript Types

Import common types for type safety:

import type {
  Database,
  Dataset,
  Chart,
  Dashboard,
  Query,
  QueryResult,
  Tab,
  Panel,
  User,
  Role,
  Permission,
  ExtensionContext,
  Disposable,
  Event,
  // ... more types
} from '@apache-superset/core';

Extension Context

The context object passed to your extension's activate function:

interface ExtensionContext {
  // Subscription management
  subscriptions: Disposable[];

  // Extension metadata
  extensionId: string;
  extensionPath: string;

  // API namespaces
  core: CoreAPI;
  commands: CommandsAPI;
  sqlLab: SqlLabAPI;
  authentication: AuthenticationAPI;
  extensions: ExtensionsAPI;
  storage: StorageAPI;
  network: NetworkAPI;
  utils: UtilsAPI;

  // Logging
  logger: Logger;
}

Event Handling

Events follow the VS Code pattern with subscribe/dispose:

// Subscribe to event
const disposable = sqlLab.onDidQueryRun((result) => {
  // Handle event
});

// Dispose when done
disposable.dispose();

// Or add to context for automatic cleanup
context.subscriptions.push(disposable);

Best Practices

Always dispose subscriptions to prevent memory leaks
Use TypeScript for better IDE support and type safety
Handle errors gracefully with try-catch blocks
Check permissions before sensitive operations
Use provided UI components for consistency
Cache API responses when appropriate
Validate user input before processing

Version Compatibility

The frontend API follows semantic versioning:

Major version: Breaking changes
Minor version: New features, backward compatible
Patch version: Bug fixes

Check compatibility in your extension.json:

{
  "engines": {
    "@apache-superset/core": "^1.0.0"
  }
}