API برنامهٔ HolyArrs

راه‌اندازی

از اسکریپت‌های خودتان، همان API نوع JSON را که برنامهٔ وب استفاده می‌کند زیر /api/v1 صدا بزنید.

اولین فراخوانی

Settings > API > API keys (تنظیمات > API > کلیدهای API) را باز کنید و کلیدی بسازید که فقط محدوده‌های لازم را داشته باشد. همین حالا آن را کپی کنید، چون فقط یک بار نشان داده می‌شود.
کلید را در هر فراخوانی در هدر X-Api-Key بفرستید. هرگز آن را در نشانی نگذارید.
نشانی پایه http://your-server:6262/api/v1 را صدا بزنید. اگر URL base برابر /holyarrs باشد، http://your-server:6262/holyarrs/api/v1 را صدا بزنید.

export HOLYARRS_KEY=...your key...
curl -H "X-Api-Key: $HOLYARRS_KEY" "http://your-server:6262/api/v1/health"

باید JSON ببینید. خطاها به شکل {"error": "plain words"} همراه با یک وضعیت HTTP برمی‌گردند. مقادیر محرمانه به‌صورت پنهان‌شده برمی‌گردند.

گزینه‌ها

انتخاب محدوده

محدوده	اجازه می‌دهد
`health_read`	فقط فید سلامت، برای ابزارهای پایش
`read`	روت‌های خواندنی، از جمله فید سلامت
`write`	تغییرها، به جز روت‌های مدیریتی و کنترل‌ها
`admin`	افراد، دعوت‌نامه‌ها، سقف درخواست‌ها، کلیدهای API، گذرواژه‌ها و تأیید دومرحله‌ای، تنظیمات ورود، بازیابی
`control`	کلیدهای بخش‌ها، مرحله‌ها، برنامه‌های متصل، راه‌اندازی مجدد و خاموش کردن
`all`	`read` و `write` و `admin`. بدون `control`

به ابزار پایش فقط health_read بدهید و چیز دیگری ندهید.

پیدا کردن روت

Settings > API نشانی پایه، محدوده‌ها، نمونه‌فراخوانی‌ها و همهٔ روت‌ها را با محدوده و دسترسی هرکدام نشان می‌دهد. وقتی وارد شده باشید، فایل OpenAPI در /api/v1/openapi.json است. روت‌های API همهٔ روت‌ها را فهرست می‌کند.

صحبت با HolyArrs مثل یک برنامهٔ قبلی

Seerr و Overseerr و Bazarr و برنامه‌های مشابه از این API استفاده نمی‌کنند. آن‌ها با HolyArrs مثل Sonarr و Radarr صحبت می‌کنند و کلیدهای مخصوص خودشان را دارند. API برنامه‌های قبلی را ببینید.

اگر کار نکرد

نشانه. خطای 401 در هر فراخوانی. علت. کلید اشتباه است یا پاک شده. راه‌حل. کلید تازه‌ای بسازید.

نشانه. خطای 403 در یک روت. علت. محدودهٔ کلید آن روت را پوشش نمی‌دهد. راه‌حل. محدودهٔ روت را در Settings > API بررسی کنید.

نشانه. خطای 404 در هر فراخوانی. علت. URL base جا افتاده است. راه‌حل. آن را پیش از /api/v1 بگذارید. URL base را ببینید.

برای حرفه‌ای‌ها

افزودن یک روت

روت‌ها در فایل routes.go هر ماژول هستند. هر روت با متد، مسیر و دسترسی خودش ثبت می‌شود، پس هر روت بررسی دسترسی دارد.

فایل openapi.json از روی روت‌ها ساخته می‌شود. وقتی این دو از هم جدا شوند TestOpenAPIGenerated شکست می‌خورد، پس آن را در همان تغییر به‌روز کنید. اگر روتی بدون به‌روزرسانی اسنپ‌شات جدول روت‌ها اضافه، حذف یا جابه‌جا شود، آن اسنپ‌شات هم شکست می‌خورد.

بعد از انتشار، مسیرها و نام فیلدها ثابت می‌مانند. فیلد اضافه کنید و هرگز نام را عوض نکنید. بعد از هر تغییر، دستور go run ./app/backend/tools/apidoc را اجرا کنید تا روت‌های API دوباره نوشته شود.

فراخوانی‌های سرور متادیتا

HolyArrs نام‌ها، تصویرها و شناسه‌ها را از سرور متادیتای HolyArrs می‌گیرد. با HOLYARRS_METADATA_URL می‌توانید یک نصب را به سرور دیگری وصل کنید. کد سرور در این مخزن نیست.

ثبت‌نام. نصب در اولین جست‌وجوی خود POST /v1/installations را بدون بدنه صدا می‌زند. پاسخ 201 است با {"schema_version":1,"token":"hai_..."}. برنامه توکن را رمزگذاری‌شده ذخیره می‌کند و در هر جست‌وجو Authorization: Bearer <token> می‌فرستد. فقط یک بار ثبت‌نام می‌کند. بعد از 401 دوباره ثبت‌نام نمی‌کند، پس نصبی که لغو شده لغو‌شده می‌ماند. اگر از سقف ساعتی برای هر گروه نشانی بگذرد، پاسخ 429 registration_limit همراه با Retry-After است.

جست‌وجو (همه GET)	روت
جست‌وجو	`/v1/search?provider=tmdb&kind=movie&q=Example&page=1`
فیلم	`/v1/movies/tmdb/{id}`
سریال	`/v1/shows/{tmdb or tvmaze}/{id}`
فصل	`/v1/shows/tmdb/{id}/seasons/{n}` (فصل 0 همان ویژه‌ها است)
موسیقی	`/v1/music/musicbrainz/{artist, release-group, release or recording}/{id}`

پارامترهای ناشناخته یا تکراری رد می‌شوند. شناسه‌های یک ارائه‌دهنده هرگز برای ارائه‌دهندهٔ دیگر استفاده نمی‌شوند.

پاسخ درست شامل schema_version، source، source_id، fetched_at، expires_at، completeness، stale و data است. HTML داخل خلاصه‌ها را متن ساده حساب کنید.

وضعیت	معنی
400	درخواست بد، دوباره تلاش نکنید
401	توکن بد یا لغوشده، دوباره تلاش نکنید
404	چنین رکوردی نیست
429	فراخوانی زیاد، تا `Retry-After` صبر کنید
503	مشغول است، صبر کنید و یک بار دوباره تلاش کنید

صفحه‌های مرتبط

HolyArrs رایگان است. اگر در وقتتان صرفه‌جویی کرد، در GitHub به آن ستاره بدهید، حمایت مالی کنید یا برای من یک قهوه بخرید.