Percona Link for MongoDB HTTP API documentation¶

Quick start guide¶

To get started with Percona Link for MongoDB API:

Ensure the service is running on http://localhost:2242
Use the /start endpoint to begin replication
Monitor progress using the /status endpoint
Use /pause and /resume to control the replication process
Call /finalize when replication is complete

Authentication¶

Currently, the API does not require authentication. However, it’s recommended to run the service behind a reverse proxy with proper authentication in production environments.

API endpoints¶

POST /start¶

Starts the replication process.

Request¶

Parameter	Type	Required	Description
`includeNamespaces`	string[]	No	List of namespaces to include in replication (e.g., [“db.*”, “db.collection”])
`excludeNamespaces`	string[]	No	List of namespaces to exclude from replication

Example:

curl -X POST http://localhost:2242/start -d '{
    "includeNamespaces": ["dbName.*", "anotherDB.collName1", "anotherDB.collName2"],
    "excludeNamespaces": ["dbName.collName"]
}'

Response¶

ok: Boolean indicating if the operation was successful.
error (optional): Error message if the operation failed.

Example:

{ "ok": true }

POST /finalize¶

Finalizes the replication process.

Request¶

Example:

curl -X POST http://localhost:2242/finalize

Response¶

ok: Boolean indicating if the operation was successful.
error (optional): Error message if the operation failed.

Example:

{ "ok": true }

POST /pause¶

Pauses the replication process.

Request¶

Example:

curl -X POST http://localhost:2242/pause

Response¶

ok: Boolean indicating if the operation was successful.
error (optional): Error message if the operation failed.

Example:

{ "ok": true }

POST /resume¶

Resumes the replication process.

Request¶

Example:

curl -X POST http://localhost:2242/resume

Resume from failure:

curl -X POST http://localhost:2242/resume -d '{
  "fromFailure": true
}'

Response¶

ok: Boolean indicating if the operation was successful.
error (optional): Error message if the operation failed.

Example:

{ "ok": true }

GET /status¶

The /status endpoint provides the current state of the Percona Link for MongoDB replication process, including its progress, lag, and event processing details.

Request¶

Example:

curl -X GET http://localhost:2242/status

Response¶

The following are response fields:

Field	Type	Description
`ok`	boolean	Operation success status
`state`	string	Current replication state
`info`	string	Additional information about the current state
`error`	string	(optional): The error message if the operation failed.
`lagTime`	number	Current lag time in logical seconds between source and target clusters.
`eventsProcessed`	number	Total events processed
`lastReplicatedOpTime`	string	The last replicated operation time.
`initialSync.completed`	boolean	Initial sync completion status
`initialSync.lagTime`	number	The lag time in logical seconds until the initial sync completed
`initialSync.cloneCompleted`	boolean	Clone process completion status
`initialSync.estimatedCloneSize`	number	Estimated total size to clone (bytes)
`initialSync.clonedSize`	number	Current cloned size (bytes)

Example:

{
    "ok": true,
    "state": "running",
    "info": "Initial Sync",

    "lagTime": 22,
    "eventsProcessed": 5000,
    "lastReplicatedOpTime": "1740335200.5",

    "initialSync": {
        "completed": false,
        "lagTime": 5,

        "cloneCompleted": false,
        "estimatedCloneSize": 5000000000,
        "clonedSize": 2500000000
    }
}

Error handling¶

The API uses standard HTTP status codes and returns error messages in the following format:

{
    "ok": false,
    "error": "Detailed error message"
}

Common error scenarios:

400 Bad Request: Invalid request parameters
404 Not Found: Endpoint not found
500 Internal Server Error: Server-side issues

Last update: June 5, 2025
Created: June 5, 2025