ss-tools/specs/008-migration-ui-improvements/contracts/api.md

API Contracts: Migration UI Improvements

Date: 2025-12-27 | Status: Implemented

Overview

This document defines the API contracts for the Migration UI Improvements feature. All endpoints follow RESTful conventions and use standard HTTP status codes.

Base URL

/api/ - All endpoints are relative to the API base URL

Authentication

All endpoints require authentication using the existing session mechanism.

Endpoints

1. List Migration Tasks

Endpoint: GET /api/tasks

Purpose: Retrieve a paginated list of migration tasks

Parameters:

limit: integer (query, optional) - Number of tasks to return (default: 10, max: 50)
offset: integer (query, optional) - Pagination offset (default: 0)
status: string (query, optional) - Filter by task status (PENDING, RUNNING, SUCCESS, FAILED, AWAITING_INPUT, AWAITING_MAPPING)

Response: 200 OK

Content-Type: application/json

Response Body:

{
  "tasks": [
    {
      "id": "string (uuid)",
      "type": "string",
      "status": "string (enum)",
      "start_time": "string (iso8601)",
      "end_time": "string (iso8601) | null",
      "requires_input": "boolean"
    }
  ],
  "total": "integer",
  "limit": "integer",
  "offset": "integer"
}

Example Request:

GET /api/tasks?limit=5&offset=0

Example Response:

{
  "tasks": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "type": "migration",
      "status": "RUNNING",
      "start_time": "2025-12-27T09:47:12.000Z",
      "end_time": null,
      "requires_input": false
    },
    {
      "id": "550e8400-e29b-41d4-a716-446655440001",
      "type": "migration",
      "status": "AWAITING_INPUT",
      "start_time": "2025-12-27T09:45:00.000Z",
      "end_time": null,
      "requires_input": true
    }
  ],
  "total": 2,
  "limit": 5,
  "offset": 0
}

Error Responses:

• 401 Unauthorized - Authentication required
• 400 Bad Request - Invalid parameters

2. Get Task Logs

Endpoint: GET /tasks/{task_id}/logs

Purpose: Retrieve detailed logs for a specific task

Parameters: None

Response: 200 OK

Content-Type: application/json

Response Body:

{
  "task_id": "string (uuid)",
  "status": "string (enum)",
  "logs": [
    {
      "timestamp": "string (iso8601)",
      "level": "string",
      "message": "string",
      "context": "object | null"
    }
  ]
}

Example Request:

GET /api/tasks/550e8400-e29b-41d4-a716-446655440001/logs

Example Response:

{
  "task_id": "550e8400-e29b-41d4-a716-446655440001",
  "status": "AWAITING_INPUT",
  "logs": [
    {
      "timestamp": "2025-12-27T09:45:00.000Z",
      "level": "INFO",
      "message": "Starting migration",
      "context": null
    },
    {
      "timestamp": "2025-12-27T09:47:12.000Z",
      "level": "ERROR",
      "message": "API error during upload",
      "context": {
        "error": "Must provide a password for the database",
        "database": "PostgreSQL"
      }
    }
  ]
}

Error Responses:

• 401 Unauthorized - Authentication required
• 404 Not Found - Task not found
• 403 Forbidden - Access denied to this task

3. Resume Task with Input

Endpoint: POST /tasks/{task_id}/resume

Purpose: Provide required input and resume a paused task

Request Body:

{
  "passwords": {
    "database_name": "password"
  }
}

Response: 200 OK

Content-Type: application/json

Response Body:

{
  "success": true,
  "message": "Task resumed successfully"
}

Example Request:

POST /api/tasks/550e8400-e29b-41d4-a716-446655440001/resume
Content-Type: application/json

{
  "passwords": {
    "PostgreSQL": "securepassword123"
  }
}

Example Response:

{
  "success": true,
  "message": "Task resumed successfully"
}

Error Responses:

• 401 Unauthorized - Authentication required
• 404 Not Found - Task not found
• 400 Bad Request - Invalid request body or missing required fields
• 409 Conflict - Task not in AWAITING_INPUT state or already completed
• 422 Unprocessable Entity - Invalid password provided

4. Get Task Details (Optional)

Endpoint: GET /tasks/{task_id}

Purpose: Get detailed information about a specific task

Parameters: None

Response: 200 OK

Content-Type: application/json

Response Body:

{
  "id": "string (uuid)",
  "type": "string",
  "status": "string (enum)",
  "start_time": "string (iso8601)",
  "end_time": "string (iso8601) | null",
  "requires_input": "boolean",
  "input_request": "object | null"
}

Example Response:

{
  "id": "550e8400-e29b-41d4-a716-446655440001",
  "type": "migration",
  "status": "AWAITING_INPUT",
  "start_time": "2025-12-27T09:45:00.000Z",
  "end_time": null,
  "requires_input": true,
  "input_request": {
    "type": "database_password",
    "databases": ["PostgreSQL"],
    "error_message": "Must provide a password for the database"
  }
}

Data Types

TaskStatus Enum

PENDING
RUNNING
SUCCESS
FAILED
AWAITING_INPUT

LogLevel Enum

INFO
WARNING
ERROR
DEBUG

Error Handling

Standard Error Format

{
  "error": {
    "code": "string",
    "message": "string",
    "details": "object | null"
  }
}

Common Error Codes

• invalid_task_id: Task ID is invalid or not found
• task_not_awaiting_input: Task is not in AWAITING_INPUT state
• invalid_password: Provided password is invalid
• unauthorized: Authentication required
• bad_request: Invalid request parameters

WebSocket Integration

Task Status Updates

Channel: /ws/tasks/{task_id}/status

Message Format:

{
  "event": "status_update",
  "task_id": "string (uuid)",
  "status": "string (enum)",
  "timestamp": "string (iso8601)"
}

Task Log Updates

Channel: /ws/tasks/{task_id}/logs

Message Format:

{
  "event": "log_update",
  "task_id": "string (uuid)",
  "log": {
    "timestamp": "string (iso8601)",
    "level": "string",
    "message": "string",
    "context": "object | null"
  }
}

Rate Limiting

• Maximum 10 requests per minute per user for task list endpoint
• Maximum 30 requests per minute per user for task details/logs endpoints
• No rate limiting for WebSocket connections

Versioning

All endpoints are versioned using the Accept header:

• Accept: application/vnd.api.v1+json - Current version

Security Considerations

1. Authentication: All endpoints require valid session authentication
2. Authorization: Users can only access their own tasks
3. Password Handling: Passwords are not stored permanently, only used for immediate task resumption
4. Input Validation: All inputs are validated according to defined schemas
5. Rate Limiting: Prevents abuse of API endpoints

Implementation Notes

1. Pagination: Default limit of 10 tasks, maximum of 50
2. Sorting: Tasks are sorted by start_time descending by default
3. Caching: Task list responses can be cached for 5 seconds
4. WebSocket: Use existing WebSocket infrastructure for real-time updates
5. Error Recovery: Failed task resumptions can be retried with corrected input

OpenAPI Specification

A complete OpenAPI 3.0 specification is available in the repository at specs/008-migration-ui-improvements/contracts/openapi.yaml.