Backups API

Base URL: https://api.sparbz.cloud/api/v1

Overview

The Backups API allows you to manage automated backups and recovery. Create backup policies, manage retention, trigger on-demand backups, and restore data from backup points.

All endpoints require authentication via Bearer token or API key.

---

Backup Management

GET /backups

List all backups in your organization.

Headers:

Authorization: Bearer <token>

Query Parameters:

Parameter	Type	Description
resource_type	string	Filter by type: database, namespace, nfs, storage
resource_id	string	Filter by resource ID
status	string	Filter by status: pending, in-progress, completed, failed, expired
limit	integer	Number of results (default: 20, max: 100)
offset	integer	Pagination offset

Response (200 OK):

[
  {
    "id": "uuid",
    "resource_type": "database",
    "resource_id": "db-xxx",
    "resource_name": "production-db",
    "status": "completed",
    "backup_type": "automatic | manual",
    "size_gb": 25.5,
    "duration_seconds": 1800,
    "creation_time": "2024-11-29T10:30:00Z",
    "completion_time": "2024-11-29T11:00:00Z",
    "retention_until": "2024-12-29T11:00:00Z",
    "storage_location": "s3://backups/prod-db/2024-11-29"
  }
]

---

GET /backups/:id

Get details of a specific backup.

Response (200 OK):

{
  "id": "uuid",
  "resource_type": "database",
  "resource_id": "db-xxx",
  "resource_name": "production-db",
  "status": "completed",
  "backup_type": "automatic",
  "size_gb": 25.5,
  "duration_seconds": 1800,
  "creation_time": "2024-11-29T10:30:00Z",
  "completion_time": "2024-11-29T11:00:00Z",
  "retention_until": "2024-12-29T11:00:00Z",
  "storage_location": "s3://backups/prod-db/2024-11-29",
  "checksum": "sha256-hash",
  "incremental": false,
  "parent_backup_id": null,
  "policy_id": "policy-xxx",
  "tags": ["daily", "automated"],
  "restore_points": 24,
  "can_restore": true
}

---

Backup Policies

GET /backup-policies

List all backup policies.

Query Parameters:

Parameter	Type	Description
resource_type	string	Filter by type: database, namespace, nfs, storage
status	string	Filter by status: enabled, disabled
limit	integer	Number of results (default: 20, max: 100)

Response (200 OK):

[
  {
    "id": "policy-xxx",
    "name": "daily-database-backups",
    "resource_type": "database",
    "resource_id": "db-xxx",
    "schedule": "0 2 * * *",
    "frequency": "daily",
    "retention_days": 30,
    "enabled": true,
    "backup_type": "incremental",
    "storage_class": "standard",
    "status": "enabled",
    "last_backup_time": "2024-11-29T02:00:00Z",
    "next_backup_time": "2024-11-30T02:00:00Z",
    "created_at": "2024-10-15T10:30:00Z"
  }
]

---

POST /backup-policies

Create a new backup policy.

Request Body:

{
  "name": "string",
  "resource_type": "database | namespace | nfs | storage",
  "resource_id": "string",
  "schedule": "cron expression (e.g., '0 2 * * *')",
  "retention_days": 30,
  "backup_type": "full | incremental",
  "storage_class": "standard | expedited",
  "enabled": true,
  "pre_backup_script": "optional bash script",
  "post_backup_script": "optional bash script"
}

Response (201 Created):

{
  "id": "policy-xxx",
  "name": "daily-database-backups",
  "resource_type": "database",
  "schedule": "0 2 * * *",
  "retention_days": 30,
  "enabled": true,
  "created_at": "2024-11-29T10:30:00Z",
  "next_backup_time": "2024-11-30T02:00:00Z"
}

---

GET /backup-policies/:id

Get details of a specific backup policy.

Response (200 OK):

{
  "id": "policy-xxx",
  "name": "daily-database-backups",
  "resource_type": "database",
  "resource_id": "db-xxx",
  "schedule": "0 2 * * *",
  "retention_days": 30,
  "backup_type": "incremental",
  "storage_class": "standard",
  "enabled": true,
  "pre_backup_script": null,
  "post_backup_script": null,
  "status": "enabled",
  "total_backups": 45,
  "next_backup_time": "2024-11-30T02:00:00Z",
  "last_backup_time": "2024-11-29T02:00:00Z",
  "created_at": "2024-10-15T10:30:00Z",
  "updated_at": "2024-11-29T15:45:00Z"
}

---

PATCH /backup-policies/:id

Update a backup policy.

Request Body:

{
  "name": "string",
  "schedule": "cron expression",
  "retention_days": 30,
  "enabled": true,
  "storage_class": "standard | expedited"
}

Response (200 OK):

{
  "id": "policy-xxx",
  "updated_at": "2024-11-29T15:45:00Z"
}

---

DELETE /backup-policies/:id

Delete a backup policy.

Response (204 No Content)

---

On-Demand Backups

POST /backups/:resource_type/:resource_id

Create an on-demand backup for a resource.

Request Body:

{
  "description": "Pre-production release backup",
  "tags": ["release-v2.0"],
  "retention_days": 90
}

Response (202 Accepted):

{
  "id": "uuid",
  "resource_type": "database",
  "resource_id": "db-xxx",
  "status": "pending",
  "creation_time": "2024-11-29T15:45:00Z",
  "estimated_duration_seconds": 1800
}

---

Backup Restoration

POST /backups/:id/restore

Restore from a backup.

Request Body:

{
  "target_resource_id": "string (optional)",
  "point_in_time": "2024-11-29T10:30:00Z (optional)",
  "restore_to_time": "2024-11-29T11:00:00Z (optional)"
}

Response (202 Accepted):

{
  "restore_job_id": "restore-job-xxx",
  "backup_id": "backup-xxx",
  "target_resource_id": "new-db-xxx",
  "status": "in-progress",
  "progress_percent": 0,
  "estimated_duration_seconds": 2400,
  "created_at": "2024-11-29T15:45:00Z"
}

---

GET /restore-jobs/:job_id

Get the status of a restore job.

Response (200 OK):

{
  "id": "restore-job-xxx",
  "backup_id": "backup-xxx",
  "target_resource_id": "new-db-xxx",
  "status": "in-progress | completed | failed",
  "progress_percent": 45,
  "bytes_restored": 11534336,
  "total_bytes": 26843545,
  "started_at": "2024-11-29T15:45:00Z",
  "estimated_completion": "2024-11-29T16:45:00Z",
  "error_message": null
}

---

GET /backups/:id/restore-points

Get available restore points for a backup.

Response (200 OK):

{
  "backup_id": "backup-xxx",
  "earliest_point": "2024-11-29T10:30:00Z",
  "latest_point": "2024-11-29T11:00:00Z",
  "available_points": [
    {
      "timestamp": "2024-11-29T10:30:00Z",
      "transaction_log_size_mb": 10
    },
    {
      "timestamp": "2024-11-29T10:45:00Z",
      "transaction_log_size_mb": 20
    },
    {
      "timestamp": "2024-11-29T11:00:00Z",
      "transaction_log_size_mb": 25
    }
  ]
}

---

Backup Verification

POST /backups/:id/verify

Verify the integrity of a backup.

Response (202 Accepted):

{
  "verification_job_id": "verify-job-xxx",
  "backup_id": "backup-xxx",
  "status": "in-progress",
  "created_at": "2024-11-29T15:45:00Z"
}

---

GET /backups/:id/verification-status

Get the verification status of a backup.

Response (200 OK):

{
  "backup_id": "backup-xxx",
  "status": "verified | failed | in-progress",
  "integrity_check": "passed",
  "corruption_detected": false,
  "checksum_match": true,
  "verified_at": "2024-11-29T11:30:00Z",
  "next_verification": "2024-12-06T11:30:00Z"
}

---

Backup Lifecycle

GET /backups/:id/lifecycle

Get the lifecycle policy for a backup.

Response (200 OK):

{
  "backup_id": "backup-xxx",
  "retention_until": "2024-12-29T11:00:00Z",
  "retention_days": 30,
  "lifecycle_actions": [
    {
      "action": "archive",
      "days": 7,
      "storage_class": "glacier"
    },
    {
      "action": "delete",
      "days": 30
    }
  ]
}

---

Backup Metrics

GET /backups/metrics

Get backup metrics across your organization.

Query Parameters:

Parameter	Type	Description
from	timestamp	Start time for metrics
to	timestamp	End time for metrics
resource_type	string	Filter by resource type

Response (200 OK):

{
  "total_backups": 256,
  "total_backup_size_gb": 2048,
  "successful_backups": 254,
  "failed_backups": 2,
  "average_backup_duration_seconds": 1800,
  "backups_by_resource_type": {
    "database": 150,
    "nfs": 80,
    "storage": 26
  },
  "backup_success_rate": 99.2,
  "estimated_storage_cost": 20.48,
  "total_restore_jobs": 12,
  "successful_restores": 11,
  "failed_restores": 1
}

---

Error Responses

Code	Description
400	Bad Request - Invalid schedule, retention, or resource ID
401	Unauthorized - Invalid or missing token
403	Forbidden - Insufficient permissions
404	Not Found - Backup, policy, or resource doesn't exist
409	Conflict - Policy already exists or resource incompatible
429	Too Many Requests - Backup limit reached
500	Internal Server Error
503	Service Unavailable - Backup service temporarily unavailable

---

Common Use Cases

Setting Up Automatic Daily Backups

POST /backup-policies
{
  "name": "daily-prod-backups",
  "resource_type": "database",
  "resource_id": "db-prod",
  "schedule": "0 2 * * *",
  "retention_days": 30,
  "backup_type": "incremental",
  "enabled": true
}

Creating a Pre-Deployment Backup

POST /backups/database/db-prod
{
  "description": "Pre-v2.0-deployment backup",
  "tags": ["deployment", "v2.0"],
  "retention_days": 90
}

Restoring from a Point in Time

POST /backups/{backup_id}/restore
{
  "point_in_time": "2024-11-29T10:45:00Z"
}

Monitoring Backup Health

GET /backups?resource_type=database&status=failed
GET /backups/metrics?from=2024-11-15T00:00:00Z&to=2024-11-29T23:59:59Z