Initial version
This commit is contained in:
Jeroen Saey
@@ -0,0 +1,476 @@
|
||||
# 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);
|
||||
```
|
||||
Reference in New Issue
Block a user