EonaCat.Sync/API.md

EonaCat.Sync REST API Documentation

Overview

The EonaCat.Sync REST API provides endpoints for managing file and database synchronization, cloud storage operations, and backup management.

Base URL

https://your-domain/api/v1

Authentication

All endpoints require authentication via bearer token:

Authorization: Bearer <token>

Endpoints

File Synchronization

POST /sync/files

Synchronizes files between two locations.

Request:

{
  "sourceDirectory": "/path/to/source",
  "targetDirectory": "/path/to/target",
  "deleteMissingInTarget": false,
  "verifyIntegrity": true,
  "excludePatterns": ["*.tmp", "*.bak"]
}

Response:

{
  "success": true,
  "changesApplied": 42,
  "conflictsEncountered": 0,
  "errors": [],
  "syncedAt": "2024-01-15T10:30:00Z",
  "executionTimeMs": 5432
}

Status Codes:

• 200 OK - Sync completed successfully
• 400 Bad Request - Invalid parameters
• 401 Unauthorized - Missing/invalid authentication
• 500 Internal Server Error - Server error

---

Database Synchronization

POST /sync/database

Synchronizes database entities between two servers.

Request:

{
  "sourceConnectionString": "Server=source;Database=db;",
  "targetConnectionString": "Server=target;Database=db;",
  "entityNames": ["Users", "Products", "Orders"],
  "useTransactions": true
}

Response:

{
  "success": true,
  "changesApplied": 1250,
  "conflictsEncountered": 3,
  "errors": [],
  "syncedAt": "2024-01-15T10:30:00Z",
  "executionTimeMs": 12543
}

---

Cloud Storage Operations

POST /cloud/{provider}/upload

Uploads a file to cloud storage.

Parameters:

• provider - Cloud provider type (azure, s3)

Request:

{
  "cloudPath": "/backups/file.zip",
  "localPath": "/local/path/file.zip",
  "metadata": {
	"backup-type": "full",
	"version": "1.0"
  }
}

Response:

{
  "success": true,
  "message": "File uploaded successfully",
  "executionTimeMs": 2341
}

---

GET /cloud/{provider}/list

Lists files in cloud storage.

Query Parameters:

• prefix - Filter by path prefix
• filter - Additional filter pattern

Response:

{
  "files": [
	{
	  "name": "backup-001.zip",
	  "path": "backups/backup-001.zip",
	  "size": 1024000000,
	  "modifiedDate": "2024-01-15T10:00:00Z",
	  "eTag": "abc123def456"
	}
  ],
  "totalCount": 5
}

---

POST /cloud/{provider}/download

Downloads a file from cloud storage.

Request:

{
  "cloudPath": "backups/file.zip",
  "localPath": "/local/download/file.zip"
}

---

GET /cloud/{provider}/shared-link

Generates a shared access link for a file.

Query Parameters:

• path - Cloud file path
• expiresIn - Expiration in seconds (default: 3600)

Response:

{
  "url": "https://storage.example.com/file?sig=...",
  "expiresAt": "2024-01-15T11:30:00Z"
}

---

Backup Management

POST /backup/create

Creates a backup of a directory.

Request:

{
  "sourceDirectory": "/path/to/backup",
  "backupPath": "/backups/location",
  "isFullBackup": false,
  "description": "Incremental backup of application data"
}

Response:

{
  "versionId": "550e8400-e29b-41d4-a716-446655440000",
  "createdAt": "2024-01-15T10:30:00Z",
  "totalSize": 5368709120,
  "fileCount": 1542,
  "isFullBackup": false,
  "changedFiles": ["file1.txt", "file2.dat"]
}

---

GET /backup/versions

Lists all backup versions.

Query Parameters:

• backupPath - Path to backup location

Response:

{
  "versions": [
	{
	  "versionId": "550e8400-e29b-41d4-a716-446655440000",
	  "createdAt": "2024-01-15T10:30:00Z",
	  "totalSize": 5368709120,
	  "fileCount": 1542,
	  "isFullBackup": false
	}
  ],
  "totalCount": 15
}

---

POST /backup/restore

Restores a backup version.

Request:

{
  "backupPath": "/backups/location",
  "versionId": "550e8400-e29b-41d4-a716-446655440000",
  "restorePath": "/restore/location"
}

---

GET /backup/restore-point-in-time

Restores to a specific point in time.

Query Parameters:

• backupPath - Path to backup location
• pointInTime - ISO 8601 datetime
• restorePath - Target restore path

---

POST /backup/prune

Deletes old backup versions.

Query Parameters:

• backupPath - Path to backup location
• retentionDays - Number of days to retain

Response:

{
  "deletedCount": 5
}

---

Merge Operations

POST /merge/files

Performs 3-way merge of files.

Request:

{
  "baseFile": "/path/to/base.txt",
  "sourceFile": "/path/to/source.txt",
  "targetFile": "/path/to/target.txt"
}

Response:

{
  "success": true,
  "mergedContent": "...",
  "conflicts": [
	{
	  "lineNumber": 42,
	  "baseContent": "original",
	  "sourceContent": "modified in source",
	  "targetContent": "modified in target",
	  "resolution": "modified in source"
	}
  ],
  "conflictResolutionCount": 1
}

---

Session Management

POST /sync/session/start

Starts a synchronization session.

Request:

{
  "sourceLocation": "System1",
  "targetLocation": "System2",
  "syncType": "Full"
}

Response:

{
  "sessionId": "session-12345",
  "startedAt": "2024-01-15T10:30:00Z",
  "sourceIdentifier": "System1",
  "targetIdentifier": "System2"
}

---

GET /sync/session/{sessionId}/status

Gets session status and progress.

Response:

{
  "sessionId": "session-12345",
  "status": "in-progress",
  "progressPercentage": 65,
  "message": "Processing database entities",
  "result": null,
  "createdAt": "2024-01-15T10:30:00Z",
  "completedAt": null
}

---

POST /sync/session/{sessionId}/complete

Completes a synchronization session.

---

Health & Monitoring

GET /health

Health check endpoint.

Response:

{
  "status": "healthy",
  "timestamp": "2024-01-15T10:30:00Z",
  "details": {
	"database": "connected",
	"storage": "available",
	"memory": "normal"
  }
}

---

GET /metrics

Gets system metrics and performance statistics.

Response:

{
  "totalSyncOperations": 1542,
  "successfulSyncs": 1523,
  "failedSyncs": 19,
  "averageSyncDuration": 5234,
  "totalDataTransferred": 1299827200,
  "cloudStorageUsage": {
	"azure": 2684354560,
	"s3": 1342177280
  }
}

---

Error Responses

All error responses follow this format:

{
  "errorCode": "SYNC_FAILED",
  "message": "Synchronization operation failed",
  "details": "Source directory not found",
  "timestamp": "2024-01-15T10:30:00Z"
}

Common Error Codes

Code	HTTP Status	Description
INVALID_REQUEST	400	Invalid request parameters
UNAUTHORIZED	401	Missing or invalid authentication
FORBIDDEN	403	Insufficient permissions
NOT_FOUND	404	Resource not found
SYNC_FAILED	500	Sync operation failed
DATABASE_ERROR	500	Database operation error
CLOUD_ERROR	503	Cloud storage unavailable

---

Rate Limiting

• Limit: 100 requests per minute per API key
• Headers: X-RateLimit-Limit, X-RateLimit-Remaining

---

Webhooks (Optional)

Subscribe to sync completion events:

POST /webhooks/subscribe
{
  "url": "https://your-app.com/webhook",
  "events": ["sync.completed", "sync.failed"]
}

---

SDK Usage Examples

C# / .NET

using HttpClient client = new HttpClient();
client.DefaultRequestHeaders.Authorization = 
	new System.Net.Http.Headers.AuthenticationHeaderValue("Bearer", token);

var request = new { 
	sourceDirectory = @"C:\source",
	targetDirectory = @"C:\target"
};

var response = await client.PostAsJsonAsync(
	"https://api.example.com/api/v1/sync/files", 
	request);

var result = await response.Content.ReadAsAsync<SyncResponseDto>();

JavaScript / Node.js

const response = await fetch('https://api.example.com/api/v1/sync/files', {
  method: 'POST',
  headers: {
	'Authorization': `Bearer ${token}`,
	'Content-Type': 'application/json'
  },
  body: JSON.stringify({
	sourceDirectory: '/path/to/source',
	targetDirectory: '/path/to/target'
  })
});

const result = await response.json();
console.log(result);