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:**
```json
{
  "sourceDirectory": "/path/to/source",
  "targetDirectory": "/path/to/target",
  "deleteMissingInTarget": false,
  "verifyIntegrity": true,
  "excludePatterns": ["*.tmp", "*.bak"]
}
```

**Response:**
```json
{
  "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:**
```json
{
  "sourceConnectionString": "Server=source;Database=db;",
  "targetConnectionString": "Server=target;Database=db;",
  "entityNames": ["Users", "Products", "Orders"],
  "useTransactions": true
}
```

**Response:**
```json
{
  "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:**
```json
{
  "cloudPath": "/backups/file.zip",
  "localPath": "/local/path/file.zip",
  "metadata": {
	"backup-type": "full",
	"version": "1.0"
  }
}
```

**Response:**
```json
{
  "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:**
```json
{
  "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:**
```json
{
  "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:**
```json
{
  "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:**
```json
{
  "sourceDirectory": "/path/to/backup",
  "backupPath": "/backups/location",
  "isFullBackup": false,
  "description": "Incremental backup of application data"
}
```

**Response:**
```json
{
  "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:**
```json
{
  "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:**
```json
{
  "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:**
```json
{
  "deletedCount": 5
}
```

---

### Merge Operations

#### POST `/merge/files`
Performs 3-way merge of files.

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

**Response:**
```json
{
  "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:**
```json
{
  "sourceLocation": "System1",
  "targetLocation": "System2",
  "syncType": "Full"
}
```

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

---

#### GET `/sync/session/{sessionId}/status`
Gets session status and progress.

**Response:**
```json
{
  "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:**
```json
{
  "status": "healthy",
  "timestamp": "2024-01-15T10:30:00Z",
  "details": {
	"database": "connected",
	"storage": "available",
	"memory": "normal"
  }
}
```

---

#### GET `/metrics`
Gets system metrics and performance statistics.

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

---

## Error Responses

All error responses follow this format:

```json
{
  "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:

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

---

## SDK Usage Examples

### C# / .NET

```csharp
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

```javascript
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);
```