مستندات API پافرلند

آدرس پایه (Base URL)

تمام درخواست‌ها به آدرس پایه‌ی زیر ارسال می‌شوند و مسیر هر endpoint در ادامه‌ی مستندات، نسبی به همین آدرس است:

https://pufferland.ir/api/client

احراز هویت

برای استفاده از API به یک کلید API نیاز دارید. کلید خود را از بخش «کلیدهای API» در حساب کاربری پنل (یا از منوی کاربری در بالای سایت) بسازید. کلید ساخته‌شده فقط یک بار نمایش داده می‌شود — آن را در جای امنی ذخیره کنید.

هر درخواست باید هدر احراز هویت را همراه داشته باشد:

Authorization: Bearer ptlc_xxxxxxxxxxxxxxxxxxxxxxxxxxxx

هدرهای درخواست

نمونه‌ی یک درخواست کامل با چند زبان:

# فهرست سرورهای شما
curl https://pufferland.ir/api/client \
  -H "Authorization: Bearer ptlc_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Accept: application/json"

const res = await fetch('https://pufferland.ir/api/client', {
  headers: {
    Authorization: 'Bearer ptlc_xxxxxxxxxxxxxxxxxxxxxxxx',
    Accept: 'application/json',
  },
});
const data = await res.json();
console.log(data.data);

import requests

r = requests.get(
    "https://pufferland.ir/api/client",
    headers={
        "Authorization": "Bearer ptlc_xxxxxxxxxxxxxxxxxxxxxxxx",
        "Accept": "application/json",
    },
)
print(r.json())

$ch = curl_init('https://pufferland.ir/api/client');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ptlc_xxxxxxxxxxxxxxxxxxxxxxxx',
        'Accept: application/json',
    ],
]);
$data = json_decode(curl_exec($ch), true);
var_dump($data);

قالب پاسخ

پاسخ‌ها با ساختار JSON استاندارد برمی‌گردند. یک منبع تکی به این شکل است:

{
  "object": "server",
  "attributes": {
    "identifier": "1a7ce997",
    "name": "Minecraft Server",
    "...": "..."
  },
  "meta": { "...": "..." }
}

و لیست‌ها به‌صورت آرایه‌ای از منابع به همراه اطلاعات صفحه‌بندی:

{
  "object": "list",
  "data": [ { "object": "...", "attributes": { "...": "..." } } ],
  "meta": {
    "pagination": {
      "total": 12, "count": 2, "per_page": 2,
      "current_page": 1, "total_pages": 6,
      "links": { "next": "..." }
    }
  }
}

پارامترهای عمومی

پارامترهای مسیر

در مستندات، مقادیری مثل {server} یا {database} پارامتر مسیر هستند؛ یعنی باید مقدار واقعی مربوط به منبع خودتان را جایگزین آن‌ها کنید. این جدول می‌گوید هر پارامتر چه چیزی است و مقدارش را از کجا پیدا کنید:

محدودیت تعداد درخواست (Rate Limit)

هر کلید API می‌تواند حداکثر ۲۴۰ درخواست در دقیقه ارسال کند. وضعیت فعلی از طریق هدرهای پاسخ قابل بررسی است:

در صورت عبور از سقف، پاسخ 409 Too Many Requests دریافت می‌کنید. بهتر است برنامه‌ی شما هدرهای بالا را رصد و بین درخواست‌ها فاصله بگذارد.

خطاها

خطاها با ساختار زیر برمی‌گردند؛ فیلد code برای تشخیص برنامه‌نویسی‌شده‌ی نوع خطا و detail برای نمایش پیام است:

{
  "errors": [
    {
      "code": "NotFoundHttpException",
      "status": "404",
      "detail": "The requested resource could not be found."
    }
  ]
}