REST API Reference

BioMapper provides a FastAPI-based REST API for strategy execution and job management.

Base URL

Default: http://localhost:8000

When running the API server:

cd /home/ubuntu/biomapper
poetry run uvicorn src.biomapper.api.main:app --reload --port 8000

Interactive Documentation

FastAPI automatically generates interactive API documentation:

Authentication

Currently no authentication is required for local development. Production deployments should implement authentication.

Core Endpoints

Health Check

Check if the API server is running and verify service status.

GET /

Response:
{
  "message": "Welcome to Biomapper API. Visit /api/docs for documentation."
}

GET /api/health

Response:
{
  "status": "healthy",
  "version": "0.5.2",
  "services": {
    "database": "connected",
    "mapper_service": "initialized",
    "resource_manager": "running"
  }
}

Strategy Execution (v2)

Execute a strategy by name or with inline YAML.

POST /api/strategies/v2/execute
Content-Type: application/json

# Option 1: Execute by strategy name
{
  "strategy": "protein_harmonization",
  "parameters": {
    "input_file": "/data/proteins.csv",
    "output_dir": "/results"
  },
  "options": {
    "checkpoint_enabled": false,
    "timeout_seconds": 3600
  }
}

# Option 2: Execute inline strategy (as dict)
{
  "strategy": {
    "name": "custom_workflow",
    "steps": [
      {
        "name": "load_data",
        "action": {
          "type": "LOAD_DATASET_IDENTIFIERS",
          "params": {
            "file_path": "/data/input.csv",
            "output_key": "data",
            "identifier_column": "id"
          }
        }
      }
    ]
  },
  "parameters": {},
  "options": {
    "checkpoint_enabled": false,
    "timeout_seconds": 3600
  }
}

Response:
{
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "running",
  "message": "Strategy execution started"
}

Additional Strategy Endpoints

POST /api/jobs/execute
Content-Type: application/json

# Full persistence support with checkpointing
{
  "strategy": "protein_harmonization",
  "parameters": {
    "input_file": "/data/proteins.csv"
  },
  "options": {
    "checkpoint_enabled": true,
    "validate_prerequisites": true
  }
}

Job Management Endpoints

Get Job Status

GET /api/jobs/{job_id}/status

Response:
{
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "running",
  "progress": 45,
  "current_step": "normalizing_proteins",
  "total_steps": 5,
  "started_at": "2024-08-13T10:00:00Z"
}

Get Job Results

GET /api/jobs/{job_id}/results

Response:
{
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "completed",
  "success": true,
  "results": {
    "datasets": {
      "proteins": [...],
      "normalized": [...]
    },
    "statistics": {
      "total_processed": 1000,
      "execution_time": 45.2
    },
    "output_files": [
      "/results/harmonized.csv"
    ]
  },
  "completed_at": "2024-08-13T10:01:00Z"
}

List All Jobs

GET /api/jobs/

Response:
[
  {
    "job_id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "completed",
    "strategy_name": "protein_harmonization",
    "created_at": "2024-08-13T10:00:00Z"
  },
  ...
]

Get Job Logs

GET /api/jobs/{job_id}/logs

Response:
{
  "logs": [
    {
      "timestamp": "2024-08-13T10:00:00Z",
      "level": "INFO",
      "message": "Starting strategy execution"
    },
    {
      "timestamp": "2024-08-13T10:00:01Z",
      "level": "INFO",
      "message": "Loading dataset from /data/proteins.csv"
    }
  ]
}

Cancel Job

POST /api/jobs/{job_id}/cancel

Response:
{
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "cancelled",
  "message": "Job cancelled successfully"
}

Pause Job

POST /api/jobs/{job_id}/pause

Response:
{
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "paused",
  "message": "Job paused successfully"
}

Resume Job

POST /api/jobs/{job_id}/resume

Response:
{
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "running",
  "message": "Job resumed successfully"
}

Checkpoint Management

List Checkpoints

GET /api/jobs/{job_id}/checkpoints

Response:
[
  {
    "checkpoint_id": "checkpoint_1",
    "created_at": "2024-08-13T10:00:30Z",
    "step_name": "after_normalization",
    "context_size": 1048576
  }
]

Restore from Checkpoint

POST /api/jobs/{job_id}/restore/{checkpoint_id}

Response:
{
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "running",
  "message": "Restored from checkpoint and resumed execution"
}

Resource Management

Get Resource Status

GET /api/status

Response:
{
  "qdrant": {
    "status": "running",
    "version": "1.9.0",
    "collections": ["metabolites", "proteins"]
  },
  "cache": {
    "status": "running",
    "entries": 1234,
    "size_mb": 45.6
  },
  "database": {
    "status": "connected",
    "jobs_count": 42
  }
}

Error Responses

The API returns standard HTTP status codes with detailed error messages:

Status Code

Description

200

Success

201

Created (job submitted)

400

Bad Request (invalid parameters)

404

Not Found (job or strategy not found)

422

Validation Error (invalid strategy format)

500

Internal Server Error

Error Response Format:

{
  "detail": "Strategy 'unknown_strategy' not found",
  "error_type": "StrategyNotFoundError",
  "status_code": 404,
  "timestamp": "2024-08-13T10:00:00Z"
}

Validation Error Format:

{
  "detail": [
    {
      "loc": ["body", "parameters", "input_file"],
      "msg": "field required",
      "type": "value_error.missing"
    }
  ]
}

Rate Limiting

Default limits (configurable):

  • 100 requests per minute per IP

  • 10 concurrent strategy executions

  • 1GB maximum request body size

Real-time Updates Support

For real-time progress updates, the API supports both Server-Sent Events (SSE) and WebSocket connections:

import requests
import json

# SSE endpoint for streaming progress
response = requests.get(
    f"http://localhost:8000/api/jobs/{job_id}/events",
    stream=True
)

for line in response.iter_lines():
    if line:
        event = json.loads(line)
        print(f"Progress: {event['progress']}%")
        print(f"Step: {event.get('current_step', 'N/A')}")

# WebSocket endpoint also available at:
# ws://localhost:8000/api/jobs/{job_id}/ws

Python Client Usage

The biomapper_client package provides a convenient Python interface:

from biomapper.client import BiomapperClient

# Synchronous usage
client = BiomapperClient(base_url="http://localhost:8000")
result = client.run("protein_harmonization", parameters={
    "input_file": "/data/proteins.csv"
})

# Async usage
async with BiomapperClient() as client:
    job = await client.execute_strategy("protein_harmonization")
    result = await client.wait_for_job(job.id)

See BiomapperClient API Reference for detailed client documentation.

—

Verification Sources

Last verified: 2025-08-17

This documentation was verified against the following project resources:

  • /biomapper/src/biomapper/api/main.py (FastAPI app configuration, routers, and middleware)

  • /biomapper/src/biomapper/api/api/routes/strategies_v2_simple.py (V2 strategy execution implementation)

  • /biomapper/src/biomapper/api/api/routes/jobs.py (Job management with persistence support)

  • /biomapper/src/biomapper/api/api/routes/health.py (Health check endpoint implementation)

  • /biomapper/src/biomapper/api/api/routes/resources.py (Resource management endpoints)

  • /biomapper/src/biomapper/api/models/strategy_execution.py (Request/response models)

  • /biomapper/pyproject.toml (API dependencies and version)