API Reference

Complete API documentation for developers extending the migration tool.

Table of contents

  1. Overview
  2. Authentication
    1. Session-Based Authentication
    2. API Headers
  3. Migration Steps API
    1. Get All Steps
    2. Get Step Details
  4. Migration Operations
    1. Start Migration
    2. Check Migration Progress
    3. Stop Migration
    4. Reset Migration Step
  5. Validation API
    1. Validate Step
    2. Get Validation Report
  6. Orchestration API
    1. Start Full Migration
    2. Get Orchestration Status
  7. Image Transfer API
    1. Transfer Images
    2. Verify Images
  8. Extension Analysis API
    1. Analyze Extensions
  9. System Information API
    1. Get System Info
    2. Health Check
  10. Logs API
    1. Get Recent Logs
  11. Error Responses
    1. Standard Error Format
    2. Common Error Codes
  12. Rate Limiting
  13. Webhooks
    1. Configure Webhooks
    2. Webhook Events
  14. SDK & Client Libraries
    1. PHP Client
    2. JavaScript Client
  15. Best Practices
    1. API Usage
    2. Error Handling
  16. Need Help?

Overview

The OpenCart Migration Tool provides a RESTful API for programmatic access to migration functionality. This allows integration with external systems, automation, and custom workflows.

API endpoints require authentication. Use session-based auth or provide credentials.

Authentication

Session-Based Authentication 

// Login endpoint
POST /login

// Request body
{
    "username": "admin",
    "password": "your_password"
}

// Response
{
    "success": true,
    "user": {
        "id": 1,
        "username": "admin"
    },
    "session_id": "abc123..."
}

API Headers 

POST /api/migrate
Content-Type: application/json
Cookie: PHPSESSID=abc123...

Migration Steps API

Get All Steps

Retrieve list of all migration steps with status.

GET /api/steps

Response:

{
    "success": true,
    "steps": [
        {
            "step_id": "default_data",
            "name": "Default Data Migration",
            "category": "core",
            "status": "completed",
            "source_count": 10,
            "target_count": 10,
            "last_run": "2025-10-09 10:30:00"
        },
        {
            "step_id": "categories",
            "name": "Categories Migration",
            "category": "core",
            "status": "pending",
            "source_count": 258,
            "target_count": 0,
            "last_run": null
        }
    ]
}

Get Step Details 

GET /api/steps/{step_id}

Response:

{
    "success": true,
    "step": {
        "step_id": "products",
        "name": "Products Migration",
        "description": "Migrate product data with images and variants",
        "category": "core",
        "status": "in_progress",
        "depends_on": ["default_data", "categories", "manufacturers"],
        "progress": {
            "total": 5000,
            "processed": 2500,
            "success": 2450,
            "failed": 50,
            "percentage": 50
        },
        "statistics": {
            "source_count": 5000,
            "target_count": 2450,
            "validation_passed": true
        }
    }
}

Migration Operations

Start Migration

Initiate migration for a specific step.

POST /api/migrate/{step_id}
Content-Type: application/json

{
    "batch_size": 1000,
    "skip_validation": false,
    "options": {
        "include_images": true
    }
}

Response:

{
    "success": true,
    "message": "Migration started successfully",
    "job_id": "migration_products_20251009_103000",
    "status": "running"
}

Check Migration Progress 

GET /api/migrate/{step_id}/progress

Response:

{
    "success": true,
    "status": "running",
    "progress": {
        "current": 2500,
        "total": 5000,
        "percentage": 50,
        "records_per_second": 45,
        "estimated_time_remaining": "2 minutes"
    },
    "statistics": {
        "success_count": 2450,
        "error_count": 50,
        "skipped_count": 0
    }
}

Stop Migration 

POST /api/migrate/{step_id}/stop

Response:

{
    "success": true,
    "message": "Migration stopped",
    "final_statistics": {
        "processed": 2500,
        "success": 2450,
        "failed": 50
    }
}

Reset Migration Step 

POST /api/migrate/{step_id}/reset

Response:

{
    "success": true,
    "message": "Migration step reset successfully",
    "step_id": "products",
    "new_status": "pending"
}

Validation API

Validate Step

Run validation for a migration step.

POST /api/validate/{step_id}

Response:

{
    "success": true,
    "validation": {
        "passed": false,
        "errors": [
            {
                "type": "count_mismatch",
                "message": "Source count (5000) != Target count (4950)",
                "severity": "high"
            }
        ],
        "warnings": [
            {
                "type": "missing_images",
                "message": "50 products missing images",
                "severity": "medium"
            }
        ]
    }
}

Get Validation Report 

GET /api/validate/{step_id}/report

Response:

{
    "success": true,
    "report": {
        "step_id": "products",
        "validation_date": "2025-10-09 11:00:00",
        "overall_status": "passed",
        "checks": [
            {
                "name": "Record Count",
                "status": "passed",
                "source_count": 5000,
                "target_count": 5000
            },
            {
                "name": "Data Integrity",
                "status": "passed",
                "details": "All foreign keys valid"
            },
            {
                "name": "Image Validation",
                "status": "warning",
                "details": "50 images missing"
            }
        ]
    }
}

Orchestration API

Start Full Migration

Execute complete migration pipeline.

POST /api/orchestrator/start
Content-Type: application/json

{
    "steps": ["default_data", "categories", "products"],
    "batch_size": 1000,
    "stop_on_error": true
}

Response:

{
    "success": true,
    "orchestration_id": "orch_20251009_103000",
    "status": "running",
    "current_step": "default_data",
    "total_steps": 3
}

Get Orchestration Status 

GET /api/orchestrator/status/{orchestration_id}

Response:

{
    "success": true,
    "orchestration": {
        "id": "orch_20251009_103000",
        "status": "running",
        "started_at": "2025-10-09 10:30:00",
        "current_step": "categories",
        "completed_steps": ["default_data"],
        "remaining_steps": ["products"],
        "progress": {
            "current": 1,
            "total": 3,
            "percentage": 33
        }
    }
}

Image Transfer API

Transfer Images

Manually trigger image transfer.

POST /api/images/transfer
Content-Type: application/json

{
    "type": "products",  // products, categories, manufacturers
    "force": false,  // Overwrite existing files
    "validate": true  // Validate after transfer
}

Response:

{
    "success": true,
    "transfer": {
        "total_files": 5000,
        "transferred": 4950,
        "skipped": 50,
        "failed": 0,
        "total_size": "2.5 GB"
    }
}

Verify Images 

POST /api/images/verify
Content-Type: application/json

{
    "type": "products"
}

Response:

{
    "success": true,
    "verification": {
        "total": 5000,
        "valid": 4950,
        "missing": 50,
        "corrupted": 0,
        "issues": [
            {
                "file": "product-123.jpg",
                "issue": "File not found",
                "product_id": 123
            }
        ]
    }
}

Extension Analysis API

Analyze Extensions

Get compatibility analysis for installed extensions.

GET /api/extensions/analyze

Response:

{
    "success": true,
    "analysis": {
        "total_extensions": 83,
        "compatible": 21,
        "missing": 62,
        "categories": {
            "payment": {
                "total": 15,
                "compatible": 10,
                "missing": 5
            },
            "shipping": {
                "total": 8,
                "compatible": 6,
                "missing": 2
            }
        },
        "extensions": [
            {
                "code": "paypal",
                "type": "payment",
                "oc3_installed": true,
                "oc4_available": true,
                "compatibility": "compatible"
            }
        ]
    }
}

System Information API

Get System Info 

GET /api/system/info

Response:

{
    "success": true,
    "system": {
        "version": "1.0.0",
        "php_version": "8.1.2",
        "mysql_version": "8.0.32",
        "memory_limit": "512M",
        "max_execution_time": 3600,
        "databases": {
            "source": {
                "connected": true,
                "database": "opencart3_db",
                "tables": 145
            },
            "target": {
                "connected": true,
                "database": "opencart4_db",
                "tables": 150
            }
        }
    }
}

Health Check 

GET /api/health

Response:

{
    "success": true,
    "status": "healthy",
    "checks": {
        "database_source": "ok",
        "database_target": "ok",
        "filesystem": "ok",
        "memory": "ok"
    }
}

Logs API

Get Recent Logs 

GET /api/logs?level=error&limit=100

Response:

{
    "success": true,
    "logs": [
        {
            "timestamp": "2025-10-09 10:35:22",
            "level": "ERROR",
            "message": "Failed to migrate product #123",
            "context": {
                "step": "products",
                "product_id": 123,
                "error": "Foreign key constraint failed"
            }
        }
    ],
    "pagination": {
        "current_page": 1,
        "total_pages": 5,
        "total_logs": 450
    }
}

Error Responses

Standard Error Format 

{
    "success": false,
    "error": {
        "code": "MIGRATION_FAILED",
        "message": "Products migration failed",
        "details": "Foreign key constraint violation",
        "step_id": "products"
    }
}

Common Error Codes

Code Description HTTP Status
AUTH_FAILED Authentication failed 401
INVALID_STEP Step ID not found 404
MIGRATION_FAILED Migration operation failed 500
VALIDATION_ERROR Data validation failed 400
DATABASE_ERROR Database connection/query error 500
PERMISSION_DENIED Insufficient permissions 403

Rate Limiting

API requests are limited to prevent abuse:

  • Public endpoints: 60 requests/minute
  • Authenticated endpoints: 300 requests/minute
  • Migration operations: 10 concurrent operations

Rate limit headers:

X-RateLimit-Limit: 300
X-RateLimit-Remaining: 250
X-RateLimit-Reset: 1696856400

Webhooks

Configure Webhooks

Register webhook URLs to receive migration events.

POST /api/webhooks
Content-Type: application/json

{
    "url": "https://your-server.com/webhook",
    "events": ["migration.completed", "migration.failed"],
    "secret": "your_webhook_secret"
}

Webhook Events

Migration Completed:

{
    "event": "migration.completed",
    "timestamp": "2025-10-09 11:00:00",
    "data": {
        "step_id": "products",
        "status": "completed",
        "statistics": {
            "processed": 5000,
            "success": 4950,
            "failed": 50
        }
    }
}

Migration Failed:

{
    "event": "migration.failed",
    "timestamp": "2025-10-09 11:00:00",
    "data": {
        "step_id": "products",
        "error": "Database connection lost",
        "partial_progress": {
            "processed": 2500,
            "success": 2450
        }
    }
}

SDK & Client Libraries

PHP Client 

use MigrationTool\Client;

$client = new Client([
    'base_url' => 'http://migration-tool.local',
    'username' => 'admin',
    'password' => 'password'
]);

// Start migration
$response = $client->migrateStep('products', [
    'batch_size' => 1000
]);

// Check progress
$progress = $client->getProgress('products');
echo "Progress: {$progress['percentage']}%";

JavaScript Client 

const MigrationClient = require('@migration-tool/client');

const client = new MigrationClient({
    baseUrl: 'http://migration-tool.local',
    credentials: {
        username: 'admin',
        password: 'password'
    }
});

// Start migration
await client.migrateStep('products', {
    batchSize: 1000
});

// Monitor progress
const progress = await client.getProgress('products');
console.log(`Progress: ${progress.percentage}%`);

Best Practices

API Usage

  • ✅ Use authentication for all requests
  • ✅ Handle rate limiting gracefully
  • ✅ Implement exponential backoff for retries
  • ✅ Monitor long-running operations
  • ✅ Validate webhook signatures

Error Handling 

try {
    await client.migrateStep('products');
} catch (error) {
    if (error.code === 'RATE_LIMIT_EXCEEDED') {
        // Wait and retry
        await sleep(error.retryAfter * 1000);
        await client.migrateStep('products');
    } else {
        // Log and handle other errors
        console.error('Migration failed:', error.message);
    }
}

Need Help?

Back to top

Copyright © 2025 Cybernamix AI. Made for the OpenCart community with ❤️