ss-tools/specs/001-migration-ui-redesign/contracts/api.md

API Contracts: Migration Process and UI Redesign

Environment Management

GET /api/environments

List all configured environments.

Response (200 OK):

[
  {
    "id": "uuid",
    "name": "Development",
    "url": "https://superset-dev.example.com"
  }
]

GET /api/environments/{id}/databases

Fetch the list of databases from a specific environment.

Response (200 OK):

[
  {
    "uuid": "db-uuid",
    "database_name": "Dev Clickhouse",
    "engine": "clickhouse"
  }
]

Database Mapping

GET /api/mappings

List all saved database mappings.

Query Parameters:

• source_env_id: Filter by source environment.
• target_env_id: Filter by target environment.

Response (200 OK):

[
  {
    "id": "uuid",
    "source_env_id": "uuid",
    "target_env_id": "uuid",
    "source_db_uuid": "uuid",
    "target_db_uuid": "uuid",
    "source_db_name": "Dev Clickhouse",
    "target_db_name": "Prod Clickhouse"
  }
]

POST /api/mappings

Create or update a database mapping.

Request Body:

{
  "source_env_id": "uuid",
  "target_env_id": "uuid",
  "source_db_uuid": "uuid",
  "target_db_uuid": "uuid"
}

POST /api/mappings/suggest

Get suggested mappings based on fuzzy matching.

Request Body:

{
  "source_env_id": "uuid",
  "target_env_id": "uuid"
}

Response (200 OK):

[
  {
    "source_db_uuid": "uuid",
    "target_db_uuid": "uuid",
    "confidence": 0.95
  }
]

Migration Execution

POST /api/migrations

Start a migration job.

Request Body:

{
  "source_env_id": "uuid",
  "target_env_id": "uuid",
  "assets": [
    {"type": "dashboard", "id": 123}
  ],
  "replace_db": true
}

Response (202 Accepted):

{
  "job_id": "uuid",
  "status": "RUNNING"
}