ss-tools/specs/010-refactor-cli-to-web/contracts/api.md

API Contracts: Refactor CLI Scripts to Web Application

1. Tools API

1.1. Search Datasets

Endpoint: POST /api/tools/search Description: Search for text patterns across all datasets in a specific environment.

Request Body:

{
  "env": "dev",
  "query": "regex_pattern"
}

Response (200 OK):

{
  "count": 5,
  "results": [
    {
      "dataset_id": 123,
      "dataset_name": "sales_data",
      "field": "sql",
      "match_context": "SELECT * FROM ...",
      "full_value": "SELECT * FROM sales WHERE ..."
    }
  ]
}

1.2. Debug Database API

Endpoint: POST /api/tools/debug/db-api Description: Test database API connectivity and structure between two environments.

Request Body:

{
  "source_env": "dev",
  "target_env": "prod"
}

Response (200 OK):

{
  "source_db_count": 10,
  "target_db_count": 12,
  "details": {
    "source_dbs": [...],
    "target_dbs": [...]
  }
}

1.3. Get Dataset Structure

Endpoint: GET /api/tools/debug/dataset/{env}/{dataset_id} Description: Retrieve the full JSON structure of a dataset.

Response (200 OK):

{
  "id": 123,
  "table_name": "sales",
  "columns": [...],
  "metrics": [...]
}

2. Connection Management API

2.1. List Connections

Endpoint: GET /api/settings/connections Response (200 OK):

[
  {
    "id": "uuid",
    "name": "Production DWH",
    "type": "postgres",
    "host": "10.0.0.1",
    "database": "dwh",
    "username": "user",
    "created_at": "2026-01-07T10:00:00Z"
  }
]

2.2. Create Connection

Endpoint: POST /api/settings/connections Request Body:

{
  "name": "Production DWH",
  "type": "postgres",
  "host": "10.0.0.1",
  "port": 5432,
  "database": "dwh",
  "username": "user",
  "password": "secret_password"
}

Response (201 Created):

{
  "id": "uuid",
  "name": "Production DWH",
  "type": "postgres",
  ...
}

2.3. Delete Connection

Endpoint: DELETE /api/settings/connections/{id} Response (204 No Content)

3. Task API (Existing, extended for Mapping)

3.1. Create Mapping Task

Endpoint: POST /api/tasks Request Body:

{
  "plugin_id": "dataset-mapper",
  "params": {
    "env": "dev",
    "dataset_id": 123,
    "source": "postgres",
    "connection_id": "uuid-of-saved-connection",
    "table_name": "sales",
    "table_schema": "public"
  }
}