مدیریت بکاپ

مرجع کامل endpointهای بخش «مدیریت بکاپ» در API کلاینت پافرلند.

Endpoints بکاپ

ساخت، دانلود، بازیابی و مدیریت بکاپ‌های سرور. مجوزهای لازم: backup.read، backup.create، backup.download، backup.delete و backup.restore.

در مسیرهای زیر {backup} شناسه‌ی UUID بکاپ است.

GET/api/client/servers/{server}/backups

فهرست تمام بکاپ‌های سرور را به‌صورت صفحه‌بندی‌شده برمی‌گرداند. فیلدهای هر بکاپ: uuid، name، ignored_files، checksum، bytes، created_at، completed_at، is_successful و is_locked.

curl "https://pufferland.ir/api/client/servers/1a85a183/backups" \
  -H "Authorization: Bearer ptlc_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Accept: application/json"

نمونه پاسخ واقعی:

{
  "object": "list",
  "data": [],
  "meta": {
    "backup_count": 0,
    "pagination": {
      "total": 0,
      "count": 0,
      "per_page": 20,
      "current_page": 1,
      "total_pages": 1,
      "links": {}
    }
  }
}

GET/api/client/servers/{server}/backups/{backup}

جزئیات یک بکاپ مشخص را برمی‌گرداند.

curl "https://pufferland.ir/api/client/servers/1a85a183/backups/9e4f7b8c-0000-0000-0000-000000000000" \
  -H "Authorization: Bearer ptlc_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Accept: application/json"

نمونه پاسخ واقعی:

{
  "object": "backup",
  "attributes": {
    "uuid": "459f3575-e9a9-40b9-bf37-fcd85adb874a",
    "is_successful": true,
    "is_locked": false,
    "name": "Nightly Backup",
    "ignored_files": [],
    "checksum": "sha1:8ed314d42402bc7d17be797e31370e07caf9adea",
    "bytes": 241660614,
    "created_at": "2026-09-16T06:21:37+03:30",
    "completed_at": "2026-09-16T06:21:39+03:30"
  }
}

POST/api/client/servers/{server}/backups

یک بکاپ جدید می‌سازد. تا پایان پردازش، checksum و completed_at در پاسخ نیستند، bytes برابر صفر و is_successful برابر false است. خطاها: 400 با کد TooManyBackupsException، 409 با کد ConflictingServerStateException و 507 برای کمبود فضا.

فیلد	نوع	الزام	توضیح
`name`	string	—	نام بکاپ؛ در صورت خالی بودن خودکار تولید می‌شود.
`ignored`	string	—	الگوهای استثنا (هر خط یک الگو)، مثل `.log` یا `cache/`.
`is_locked`	boolean	—	قفل در برابر حذف؛ پیش‌فرض `false`.

curl -X POST "https://pufferland.ir/api/client/servers/1a85a183/backups" \
  -H "Authorization: Bearer ptlc_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"name": "Nightly Backup"}'

await fetch('https://pufferland.ir/api/client/servers/1a85a183/backups', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer ptlc_xxxxxxxxxxxxxxxxxxxxxxxx',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ name: 'Nightly Backup' }),
});

import requests

r = requests.post(
    "https://pufferland.ir/api/client/servers/1a85a183/backups",
    json={"name": "Nightly Backup"},
    headers={"Authorization": "Bearer ptlc_xxxxxxxxxxxxxxxxxxxxxxxx"},
)
print(r.json())

curl_post('https://pufferland.ir/api/client/servers/1a85a183/backups', [
    CURLOPT_POSTFIELDS => json_encode(['name' => 'Nightly Backup']),
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ptlc_xxxxxxxxxxxxxxxxxxxxxxxx',
        'Content-Type: application/json',
    ],
]);

نمونه پاسخ واقعی:

{
  "object": "backup",
  "attributes": {
    "uuid": "459f3575-e9a9-40b9-bf37-fcd85adb874a",
    "is_successful": false,
    "is_locked": false,
    "name": "Nightly Backup",
    "ignored_files": [],
    "checksum": null,
    "bytes": 0,
    "created_at": "2026-09-16T06:21:37+03:30",
    "completed_at": null
  }
}

GET/api/client/servers/{server}/backups/{backup}/download

یک URL دانلود امضاشده برمی‌گرداند (attributes.url) که یک ساعت معتبر است و آرشیو فشرده‌ی tar.gz را می‌دهد. برای هر فراخوانی URL جدیدی تولید می‌شود و نیازی به احراز هویت اضافه ندارد.

خطاها: 400 با کد BackupNotCompletedException یا BackupFailedException.

curl "https://pufferland.ir/api/client/servers/1a85a183/backups/9e4f7b8c-0000-0000-0000-000000000000/download" \
  -H "Authorization: Bearer ptlc_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Accept: application/json"

نمونه پاسخ واقعی:

{
  "object": "signed_url",
  "attributes": {
    "url": "https://p5.pfmc.ir:8080/download/backup?token=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiIsImp0aSI6…"
  }
}

توکن URL امضاشده در خروجی واقعی بسیار طولانی است و در اینجا کوتاه شده است. هر فراخوانی، URL جدیدی با یک ساعت اعتبار تولید می‌کند.

DELETE/api/client/servers/{server}/backups/{backup}

بکاپ را برای همیشه حذف می‌کند. پاسخ موفق: 204. اگر بکاپ قفل باشد خطای 400 با کد BackupIsLockedException می‌گیرید.

curl -X DELETE "https://pufferland.ir/api/client/servers/1a85a183/backups/9e4f7b8c-0000-0000-0000-000000000000" \
  -H "Authorization: Bearer ptlc_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Accept: application/json"

نمونه پاسخ واقعی:

204 No Content

POST/api/client/servers/{server}/backups/{backup}/restore

سرور را از بکاپ بازیابی می‌کند (پاسخ 202). سرور ابتدا خاموش، در صورت نیاز فایل‌ها پاک، آرشیو استخراج و سپس سرور آماده می‌شود. خطاها: 400 با کد BackupNotCompletedException و 409 در حالت نصب.

فیلد	نوع	الزام	توضیح
`truncate`	boolean	—	پاک‌کردن فایل‌های فعلی قبل از بازیابی؛ پیش‌فرض `true`.

curl -X POST "https://pufferland.ir/api/client/servers/1a85a183/backups/9e4f7b8c-0000-0000-0000-000000000000/restore" \
  -H "Authorization: Bearer ptlc_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"truncate": true}'

POST/api/client/servers/{server}/backups/{backup}/lock

وضعیت قفل بکاپ را تغییر می‌دهد (قفل ⇄ باز). بکاپ قفل‌شده حذف نمی‌شود. پاسخ موفق: 200 بدون بدنه.

curl -X POST "https://pufferland.ir/api/client/servers/1a85a183/backups/9e4f7b8c-0000-0000-0000-000000000000/lock" \
  -H "Authorization: Bearer ptlc_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json"

نمونه پاسخ واقعی:

204 No Content