Implementation:TobikoData Sqlmesh VSCode OpenAPI Spec
| Knowledge Sources | |
|---|---|
| Domains | API_Documentation, VSCode_Extension, Web_API |
| Last Updated | 2026-02-07 20:00 GMT |
Overview
OpenAPI 3.1 specification defining the SQLMesh VSCode extension API contract.
Description
This OpenAPI specification defines the RESTful API exposed by the SQLMesh server backend for the VSCode extension. It documents all available endpoints, request/response schemas, and operations that the extension uses to communicate with the SQLMesh engine.
The spec follows OpenAPI 3.1.0 standard and is generated by FastAPI, which provides automatic API documentation and validation. Key API operations include:
- apply: Apply a SQLMesh plan to an environment
- evaluate: Execute and evaluate a model with configurable limits
- Additional endpoints for plan generation, testing, and project management
This specification serves as the contract between the VSCode extension frontend and the SQLMesh Python backend, ensuring type safety and consistent API behavior.
Usage
This file is used for API documentation, client code generation, and runtime validation. Developers can reference it to understand available endpoints, and tools can generate TypeScript types or API clients from it.
Code Reference
Source Location
- Repository: TobikoData_Sqlmesh
- File: vscode/openapi.json
Signature
{
"openapi": "3.1.0",
"info": {
"title": "FastAPI",
"version": "0.1.0"
},
"paths": {
"/api/commands/apply": { ... },
"/api/commands/evaluate": { ... },
...
},
"components": {
"schemas": { ... }
}
}
Import
# Generate TypeScript types
openapi-typescript vscode/openapi.json -o vscode/extension/src/generated/api.ts
# View in Swagger UI
swagger-ui vscode/openapi.json
I/O Contract
Inputs
| Name | Type | Required | Description |
|---|---|---|---|
| FastAPI Server | Python App | Yes | Running SQLMesh FastAPI server that implements this spec |
Outputs
| Name | Type | Description |
|---|---|---|
| API Documentation | HTML | Interactive API docs (Swagger UI / ReDoc) |
| Type Definitions | TypeScript | Generated types for VSCode extension |
| Validation Schema | JSON Schema | Request/response validation rules |
Implementation Details
Key Endpoints
POST /api/commands/apply
- Purpose: Apply a SQLMesh plan to update an environment
- Request Body: Plan configuration and target environment
- Response: PlanApplyStageTracker or null
- Error: 422 Validation Error
POST /api/commands/evaluate
- Purpose: Evaluate a model with default limit of 1000 rows
- Request Body: Model identifier and evaluation parameters
- Response: Evaluation results with data preview
- Error: 422 Validation Error
Schema Components
The spec defines reusable schemas in the `components/schemas` section:
- PlanApplyStageTracker: Tracks progress of plan application
- HTTPValidationError: Standard validation error format
- Body_initiate_apply_api_commands_apply_post: Request schema for apply operation
- Additional model schemas for SQLMesh entities (snapshots, environments, etc.)
Response Formats
- Success Responses: 200 OK with JSON payload
- Validation Errors: 422 Unprocessable Entity with error details
- Content Type: application/json for all endpoints
File Characteristics
- Size: 2,240 lines
- Format: JSON
- Generation: Auto-generated by FastAPI from Python type hints
- Version: OpenAPI 3.1.0 (latest spec version)
Generation Process
The spec is automatically generated from FastAPI route definitions:
# In Python backend
from fastapi import FastAPI
app = FastAPI()
@app.post("/api/commands/apply")
async def initiate_apply(request: ApplyRequest) -> PlanApplyStageTracker | None:
"""Apply a plan"""
...
# FastAPI auto-generates OpenAPI spec from type hints
Usage Examples
// Generated TypeScript client usage
import { paths } from './generated/api'
type ApplyRequest = paths['/api/commands/apply']['post']['requestBody']['content']['application/json']
type ApplyResponse = paths['/api/commands/apply']['post']['responses']['200']['content']['application/json']
// Make API request
const response = await fetch('http://localhost:8000/api/commands/apply', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify(applyRequest),
})
const data: ApplyResponse = await response.json()
# View interactive API docs
# Start SQLMesh server, then navigate to:
http://localhost:8000/docs # Swagger UI
http://localhost:8000/redoc # ReDoc alternative
# Generate client code
npx openapi-generator-cli generate \
-i vscode/openapi.json \
-g typescript-fetch \
-o vscode/extension/src/generated