API Usage Guide

This guide covers how to interact directly with the DBConvert Streams API for managing streams and connections programmatically.

Authentication

All API requests require an API key in the header:

X-API-Key: YOUR_API_KEY

You can obtain your API key from https://streams.dbconvert.com/account.

Connection Management

Create Connection

Create database connections for source and target databases.

MySQL Connection

curl -X POST "http://localhost:8020/api/v1/connections" \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
  "type": "MySQL",
  "name": "mysql-source",
  "host": "mysql-host",
  "port": 3306,
  "database": "source_db",
  "username": "user",
  "password": "password"
}'

PostgreSQL Connection

curl -X POST "http://localhost:8020/api/v1/connections" \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
  "type": "PostgreSQL",
  "name": "postgres-target",
  "host": "postgres-host",
  "port": 5432,
  "database": "target_db",
  "username": "user",
  "password": "password"
}'

Response includes a connection ID:

{
  "created": 1739572516,
  "id": "conn_2t3EmXcvcg2J6I9mJ02UaiMVxfb"
}

Store these connection IDs for creating streams.

Stream Configuration

Create Stream Configuration

curl -X POST "http://localhost:8020/api/v1/stream-configs" \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
  "name": "my-stream",
  "source": "SOURCE_CONNECTION_ID",
  "target": "TARGET_CONNECTION_ID",
  "mode": "convert",
  "dataBundleSize": 500,
  "reportingIntervals": {
    "source": 3,
    "target": 3
  },
  "tables": [
    {
      "name": "table_name"
    }
  ],
  "limits": {
    "numberOfEvents": 0,
    "elapsedTime": 0
  },
  "createStructure": true
}'

Configuration Options

Field	Description	Default
name	Stream name (suffix added automatically)	Required
source	Source connection ID	Required
target	Target connection ID	Required
mode	"convert" or "cdc"	Required
dataBundleSize	Records per batch (10-1000)	500
reportingIntervals	Progress reporting frequency in seconds	3
tables	Array of tables to process	Required
limits	Optional processing limits	None
createStructure	Create tables in target if missing	true

Response includes configuration ID:

{
  "id": "config_2t3HO553pbKiTFEk77OaghU45qA",
  "name": "my-stream_U45qA",
  ...
}

Stream Operations

Start Stream

curl -X POST "http://localhost:8020/api/v1/streams/CONFIG_ID/start" \
-H "X-API-Key: YOUR_API_KEY"

Response includes stream ID:

{
  "id": "stream_2t3HSWnLvjeOCuuVPsuJVUhawj2"
}

Pause Stream

curl -X POST "http://localhost:8020/api/v1/streams/STREAM_ID/pause" \
-H "X-API-Key: YOUR_API_KEY"

Resume Stream

curl -X POST "http://localhost:8020/api/v1/streams/STREAM_ID/resume" \
-H "X-API-Key: YOUR_API_KEY"

Stop Stream

curl -X POST "http://localhost:8020/api/v1/streams/STREAM_ID/stop" \
-H "X-API-Key: YOUR_API_KEY"

Check Stream Status

curl "http://localhost:8020/api/v1/streams/STREAM_ID/stats" \
-H "X-API-Key: YOUR_API_KEY"

Example response:

{
  "configID": "config_2t3HO553pbKiTFEk77OaghU45qA",
  "streamID": "stream_2t3HSWnLvjeOCuuVPsuJVUhawj2",
  "nodes": [
    {
      "id": "nodetarget_2t3HSgRcd8ytJfDYw88ZBveaRjt",
      "type": "target",
      "stat": {
        "failedCounter": 0,
        "counter": 403000,
        "prevDataSize": 921447141,
        "sumDataSize": 1282792782,
        "reportingInterval": 0,
        "start": "2025-02-14T22:57:18.363865111Z",
        "duration": 0,
        "avgRate": 0,
        "status": "PAUSED"
      }
    }
  ]
}

Stream States

Streams can be in the following states:

• READY: Initial state after creation
• RUNNING: Active data transfer
• PAUSED: Temporarily suspended
• STOPPED: Terminated (cannot be resumed)
• FINISHED: Successful completion
• FAILED: Error state

Error Handling

Common HTTP status codes:

• 400: Invalid request (check payload format)
• 403: Invalid API key
• 404: Resource not found
• 409: Conflict (e.g., starting new stream while others are paused)
• 500: Server error

Best Practices

1. Connection Management

   • Store connection IDs securely
   • Test connections before creating streams
   • Use descriptive connection names

2. Stream Configuration

   • Start with smaller dataBundleSize (500) and adjust based on performance
   • Use meaningful stream names
   • Consider setting reasonable limits for unattended operations

3. Operations

   • Monitor stream status regularly
   • Handle FAILED state appropriately
   • Stop unused streams to free resources

4. Error Handling

   • Implement proper error handling in your code
   • Log all API responses
   • Set up monitoring for stream status

For additional information, refer to the complete API Reference.