ה-API של HolyArrs

קרא לאותו JSON API שאפליקציית ה-web משתמשת בו, תחת /api/v1, מהסקריפטים שלך.

הקריאה הראשונה שלך

1. פתח את Settings > API > API keys (הגדרות > API > מפתחות API) וצור מפתח עם ההרשאות שהוא צריך בלבד. העתק אותו עכשיו, כי הוא מוצג פעם אחת.
2. שלח אותו בכותרת X-Api-Key בכל קריאה. אל תשים אותו בכתובת.
3. קרא לכתובת הבסיס 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. סודות חוזרים מוסתרים.

אפשרויות

בחירת scope

Scope	מאפשר
health_read	רק את פיד התקינות, לכלי ניטור
read	את נתיבי הקריאה, כולל פיד התקינות
write	שינויים, חוץ מנתיבי ניהול ובקרה
admin	אנשים, הזמנות, מגבלות בקשות, מפתחות API, סיסמאות ואימות דו-שלבי, הגדרות התחברות, שחזור
control	מתגי חלקים, שלבים, אפליקציות מקושרות, הפעלה מחדש וכיבוי
all	read, write ו-admin. לא control

לכלי ניטור תן health_read ותו לא.

איך מוצאים נתיב

Settings > API מציג את כתובת הבסיס, את ה-scopes, קריאות לדוגמה, וכל נתיב עם ה-scope וההרשאה שלו. קובץ ה-OpenAPI נמצא ב-/api/v1/openapi.json כשאתה מחובר. נתיבי ה-API מפרט את כל הנתיבים.

לדבר עם HolyArrs כמו אפליקציה קודמת

Seerr, Overseerr, Bazarr ואפליקציות דומות לא משתמשות ב-API הזה. הן מדברות עם HolyArrs כאילו הוא Sonarr ו-Radarr, עם מפתחות משלהן. ראה API לאפליקציות קודמות.

אם זה לא עובד

תסמין. 401 בכל קריאה. סיבה. המפתח שגוי או נמחק. פתרון. צור מפתח חדש.

תסמין. 403 בנתיב אחד. סיבה. ה-scope של המפתח לא מכסה את הנתיב. פתרון. בדוק את ה-scope של הנתיב ב-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_..."}. האפליקציה שומרת את ה-token מוצפן ושולחת 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	token שגוי או מבוטל, אל תנסה שוב
404	אין רשומה כזו
429	יותר מדי קריאות, חכה ל-Retry-After
503	עסוק, חכה ונסה שוב פעם אחת

קשור

• נתיבי ה-API
• API לאפליקציות קודמות
• משתני סביבה