Skip to main content

REST API

The Teckel HTTP server is built with Axum and provides a RESTful interface for the Teckel UI and external clients. CORS is enabled for all origins.

Endpoints​

GET /api/health​

Health check.

Response 200 OK:

{
"status": "ok",
"version": "0.1.0"
}

POST /api/validate​

Validates a pipeline YAML without executing it.

Request:

{
"yaml": "version: '3.0'\npipeline:\n ...",
"variables": {
"ENV": "dev"
}
}

Response 200 OK:

{
"valid": true
}

Response 200 OK (invalid pipeline):

{
"valid": false,
"error": "V-001: asset \"missing\" references unknown asset \"nonexistent\""
}

POST /api/explain​

Generates a human-readable execution plan.

Request: Same as /api/validate.

Response 200 OK:

{
"plan": "=== Pipeline Execution Plan ===\n\n--- Inputs ---\n [raw_data] format=csv, path=data.csv\n\n--- Transformations ---\n [filtered] WHERE (from: raw_data)\n\n--- Outputs ---\n [result] from=filtered, format=parquet, mode=Overwrite, path=output.parquet\n\nTotal: 1 inputs, 1 transformations, 1 outputs\nExecution waves: 3\n Wave 0: raw_data\n Wave 1: filtered\n Wave 2: result"
}

Response 400 Bad Request:

{
"error": "parse error: ..."
}

POST /api/jobs​

Submits a pipeline for asynchronous execution. The pipeline is validated first (fail-fast). If valid, the job is queued for execution by the worker pool.

Request: Same as /api/validate.

Response 202 Accepted:

{
"job_id": "550e8400-e29b-41d4-a716-446655440000",
"status": "queued"
}

Response 400 Bad Request (validation failure):

{
"error": "validation failed: V-001: ..."
}

GET /api/jobs​

Lists all jobs.

Response 200 OK:

{
"jobs": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"status": "completed",
"created_at": "2025-01-15T10:30:00Z",
"started_at": "2025-01-15T10:30:01Z",
"completed_at": "2025-01-15T10:30:05Z",
"duration_ms": 4000
}
]
}

GET /api/jobs/{id}​

Gets the status of a specific job.

Response 200 OK:

{
"id": "550e8400-e29b-41d4-a716-446655440000",
"status": "running",
"created_at": "2025-01-15T10:30:00Z",
"started_at": "2025-01-15T10:30:01Z"
}

Response 404 Not Found:

{
"error": "job not found"
}

GET /api/jobs/{id}/wait​

Long-polls until the job reaches a terminal state (completed, failed, or cancelled). Optional query parameter timeout specifies the maximum wait time in seconds (default: 300).

Example: GET /api/jobs/550e8400.../wait?timeout=60

Response 200 OK:

{
"id": "550e8400-e29b-41d4-a716-446655440000",
"status": "completed",
"created_at": "2025-01-15T10:30:00Z",
"started_at": "2025-01-15T10:30:01Z",
"completed_at": "2025-01-15T10:30:05Z",
"duration_ms": 4000
}

If the timeout expires before the job completes, the current job status is returned (which may still be running or queued).

DELETE /api/jobs/{id}​

Cancels a running or queued job. Uses CancellationToken from tokio-util to signal the running task.

Response 200 OK:

{
"status": "cancelling"
}

If the job was queued (not yet started), it is immediately marked as cancelled. If the job is running, cancellation is cooperative -- the task is signaled via tokio::select! and will stop at the next await point.

Response 404 Not Found:

{
"error": "job not found"
}

Job Status Values​

StatusDescription
queuedJob is waiting in the worker pool queue
runningJob is actively executing
completedJob finished successfully
failedJob encountered an error
cancelledJob was cancelled by the user

Authentication​

The current API does not include authentication. For production deployments, place the server behind a reverse proxy (nginx, Traefik, etc.) that handles authentication and TLS termination.