Implementation:TobikoData Sqlmesh Api Instance

Knowledge Sources	TobikoData_Sqlmesh
Domains	Web_UI, HTTP_Client
Last Updated	2026-02-07 20:00 GMT

Overview

Core HTTP client for the SQLMesh web UI, handling all API communication with the backend server.

Description

The Api_Instance module provides the foundational fetchAPI function for making HTTP requests to the SQLMesh backend. It handles request formatting, response parsing, error handling, and supports multiple content types including JSON, Apache Arrow streams, and Server-Sent Events. The module includes URL prefix management for deployment flexibility and automatically handles credentials for authenticated requests.

Usage

Use this module as the primary HTTP client for all API calls in the SQLMesh web UI. It provides consistent error handling, type-safe request/response handling, and automatic content-type detection.

Code Reference

Source Location

Repository: TobikoData_Sqlmesh
File: web/client/src/api/instance.ts

Signature

export async function fetchAPI<T = any, B extends object = any>(
  config: FetchOptions<B>,
  options?: Partial<FetchOptionsWithSignal>,
): Promise<T & ResponseWithDetail>

export function getUrlWithPrefix(url?: string): string

export interface FetchOptions<B extends object = any> {
  url: string
  method: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH'
  data?: B
  responseType?: string
  headers?: Record<string, string>
  credentials?: 'omit' | 'same-origin' | 'include'
  mode?: 'cors' | 'no-cors' | 'same-origin'
  cache?: 'default' | 'no-store' | 'reload' | 'no-cache' | 'force-cache' | 'only-if-cached'
  params?: Record<string, Maybe<string | number | boolean>>
}

Import

import fetchAPI, { getUrlWithPrefix } from '@api/instance'

I/O Contract

Inputs

Name	Type	Required	Description
config.url	string	Yes	API endpoint URL (relative or absolute)
config.method	string	Yes	HTTP method (GET, POST, PUT, DELETE, PATCH)
config.data	object	No	Request body data (automatically JSON serialized)
config.params	Record<string, any>	No	URL query parameters
config.headers	Record<string, string>	No	Additional HTTP headers
options.signal	AbortSignal	No	Abort signal for request cancellation

Outputs

Name	Type	Description
Response	T & ResponseWithDetail	Typed response data with ok flag and optional detail message

Implementation Details

Content Type Support

application/json: Standard JSON responses (most common)
application/vnd.apache.arrow.stream: Apache Arrow IPC format for large datasets
text/event-stream: Server-Sent Events for streaming responses

Error Handling

Status 204: Returns {ok: true} for successful no-content responses
Status 400+: Automatically parses error JSON and throws with status information
Network errors: Properly propagates fetch errors with status text

URL Management

The getUrlWithPrefix function ensures proper URL construction:

Reads base URL from window.__BASE_URL__ global variable
Normalizes double slashes in paths
Supports deployment in subdirectories

Usage Examples

import fetchAPI from '@api/instance'

// GET request with query parameters
const models = await fetchAPI<Model[]>({
  url: '/api/models',
  method: 'GET',
  params: { environment: 'prod' }
})

// POST request with body data
const result = await fetchAPI<PlanResult>({
  url: '/api/plan',
  method: 'POST',
  data: {
    environment: 'dev',
    auto_apply: false
  }
})

// Request with abort signal
const controller = new AbortController()
const data = await fetchAPI(
  { url: '/api/lineage', method: 'GET' },
  { signal: controller.signal }
)
// Later: controller.abort()

Related Pages

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment