HolyArrs API

Из својих скрипти позивај исти JSON API који користи и веб апликација, под /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 статус. Тајне се враћају маскиране.

Опције

Изабери опсег

Опсег	Дозвољава
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	Заузет, сачекај и покушај поново једном

Повезане странице

• API руте
• API за претходне апликације
• Променљиве окружења