شروع سریع API ابران با curl | مستندات ابران

این راهنما یک درخواست واقعی و امن به API ابران می‌فرستد. در پایان می‌توانید هویت فعلی را بررسی کنید، شناسه پروژه را پیدا کنید و resourceهای همان پروژه را بخوانید.

پیش‌نیازها

یک حساب و پروژه فعال در ابران
یک API token معتبر
curl و یک ابزار خواندن JSON مانند jq

token را از Console بسازید و فقط در secret store نگه دارید. آن را در repository، تصویر Docker، فایل قابل اشتراک یا خروجی CI قرار ندهید. جزئیات ساخت و rotation در راهنمای API token و امنیت حساب آمده است.

۱. تنظیم آدرس و token

آدرس production API برابر https://api.abr.run است. متغیرها را برای session فعلی shell تنظیم کنید:


export ABRUN_API_URL='https://api.abr.run'
export ABRUN_TOKEN='<your-api-token>'

قرار دادن token پس از export ممکن است آن را در history شل ذخیره کند. در محیط واقعی، مقدار را از secret manager یا ورودی امن shell بخوانید و پس از پایان session پاک کنید.

۲. بررسی احراز هویت

درخواست زیر کاربر متناظر با token را برمی‌گرداند:


curl --fail-with-body --silent --show-error \
  --header "Authorization: Bearer $ABRUN_TOKEN" \
  "$ABRUN_API_URL/v1/auth/me" | jq

اگر پاسخ 401 Unauthorized است، token وجود ندارد، نامعتبر است یا منقضی شده است. اگر 403 Forbidden می‌گیرید، هویت معتبر است اما مجوز عملیات را ندارد.

۳. پیدا کردن شناسه پروژه

فهرست پروژه‌های حساب را دریافت کنید:


curl --fail-with-body --silent --show-error \
  --header "Authorization: Bearer $ABRUN_TOKEN" \
  "$ABRUN_API_URL/v1/projects" | jq

پاسخ این endpoint یک آرایه از پروژه‌ها است. مقدار عددی id پروژه موردنظر را انتخاب کنید:


export ABRUN_PROJECT_ID='<project-id>'

۴. خواندن resourceهای پروژه

endpointهای collection پروژه‌ای مانند فهرست Appها به هدر X-Project-ID نیاز دارند:


curl --fail-with-body --silent --show-error \
  --header "Authorization: Bearer $ABRUN_TOKEN" \
  --header "X-Project-ID: $ABRUN_PROJECT_ID" \
  "$ABRUN_API_URL/v1/apps" | jq

این فهرست یک پاسخ صفحه‌بندی‌شده دارد:


{
  "items": [],
  "total": 0,
  "limit": 20,
  "offset": 0
}

برای endpointهای item مانند /v1/apps/{appID} معمولاً هدر پروژه لازم نیست؛ API مالکیت resource و دسترسی شما را از خود شناسه بررسی می‌کند. وجود یک شناسه به معنی دسترسی به آن نیست.

ارسال JSON

برای درخواست‌هایی که body دارند، Content-Type را صریح بفرستید. این نمونه فقط الگوی صحیح ارسال JSON را نشان می‌دهد؛ پیش از استفاده، فیلدهای endpoint موردنظر را در مرجع API بررسی کنید.


curl --fail-with-body --silent --show-error \
  --request POST \
  --header "Authorization: Bearer $ABRUN_TOKEN" \
  --header "X-Project-ID: $ABRUN_PROJECT_ID" \
  --header 'Content-Type: application/json' \
  --data '{"name":"example"}' \
  "$ABRUN_API_URL/v1/apps" | jq

خواندن پاسخ و خطا

یک resource به‌صورت object مستقیم برمی‌گردد. فهرست‌های صفحه‌بندی‌شده شامل items، total، limit و offset هستند و عملیات بدون body می‌توانند 204 No Content برگردانند.

خطای API این envelope پایدار را دارد:


{
  "error": {
    "code": "error_code",
    "message": "A readable explanation"
  }
}

automation باید ابتدا HTTP status و سپس error.code را بررسی کند. روی متن message یا جزئیات داخلی provider، Kubernetes و دیتابیس شرط نگذارید. --fail-with-body باعث می‌شود curl در statusهای ناموفق exit code غیرصفر بدهد و در عین حال body خطا را برای عیب‌یابی حفظ کند.

پاک‌کردن secret محلی

بعد از پایان کار، token را از محیط shell حذف کنید:


unset ABRUN_TOKEN ABRUN_PROJECT_ID

قدم بعدی

برای قواعد کامل پاسخ‌ها و تغییر قرارداد، مرجع API ابران را بخوانید. اگر commandهای آماده و خروجی table، JSON یا YAML می‌خواهید، به مرجع CLI ابران بروید.