HolyArrs API

Izsauc no saviem skriptiem to pašu JSON API, ko izmanto tīmekļa lietotne, ar ceļu /api/v1.

Veic pirmo izsaukumu

1. Atver Settings > API > API keys (Iestatījumi > API > API atslēgas) un izveido atslēgu tikai ar tām darbības jomām, kas tai vajadzīgas. Nokopē to uzreiz, jo tā tiek parādīta tikai vienu reizi.
2. Sūti to galvenē X-Api-Key katrā izsaukumā. Nekad neliec to adresē.
3. Izsauc pamatadresi http://your-server:6262/api/v1. Ja URL base ir /holyarrs, izsauc 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"

Tev vajadzētu saņemt JSON. Kļūdas ir {"error": "plain words"} ar HTTP statusu. Noslēpumi tiek atgriezti maskēti.

Izvēles

Izvēlies darbības jomu

Darbības joma	Ļauj
health_read	Tikai veselības plūsmu, uzraudzības rīkiem
read	Lasīšanas maršrutus, ieskaitot veselības plūsmu
write	Izmaiņas, izņemot administratora maršrutus un vadības darbības
admin	Cilvēkus, ielūgumus, pieprasījumu limitus, API atslēgas, paroles un divfaktoru autentifikāciju, pieteikšanās iestatījumus, atjaunošanu
control	Daļu slēdžus, posmus, saistītās lietotnes, restartēšanu un izslēgšanu
all	read, write un admin. Bez control

Uzraudzības rīkam dod health_read un neko citu.

Atrodi maršrutu

Settings > API rāda pamatadresi, darbības jomas, piemēru izsaukumus un katru maršrutu ar tā darbības jomu un atļauju. OpenAPI fails ir pieejams /api/v1/openapi.json, kad esi pieteicies. API maršruti uzskaita katru maršrutu.

Runā ar HolyArrs kā ar iepriekšējo lietotni

Seerr, Overseerr, Bazarr un līdzīgas lietotnes šo API neizmanto. Tās runā ar HolyArrs tā, it kā tas būtu Sonarr un Radarr, ar savām atslēgām. Skaties Old-app API.

Ja tas nedarbojas

Simptoms. 401 katrā izsaukumā. Cēlonis. Atslēga ir nepareiza vai izdzēsta. Risinājums. Izveido jaunu atslēgu.

Simptoms. 403 vienā maršrutā. Cēlonis. Atslēgas darbības joma neattiecas uz šo maršrutu. Risinājums. Pārbaudi maršruta darbības jomu sadaļā Settings > API.

Simptoms. 404 katrā izsaukumā. Cēlonis. Trūkst URL base. Risinājums. Ieliec to pirms /api/v1. Skaties URL base.

Pieredzējušiem

Pievienot maršrutu

Maršruti atrodas katra moduļa failā routes.go. Katrs tiek reģistrēts ar savu metodi, ceļu un atļauju, tāpēc katram maršrutam ir atļaujas pārbaude.

openapi.json tiek veidots no maršrutiem. TestOpenAPIGenerated kļūst sarkans, ja tie nesakrīt, tāpēc atjaunini to tajā pašā izmaiņā. Arī maršrutu tabulas momentuzņēmums kļūst sarkans, ja maršruts tiek pievienots, noņemts vai pārvietots bez momentuzņēmuma atjaunināšanas.

Kad versija ir izlaista, ceļi un lauku nosaukumi paliek. Pievieno laukus, nekad tos nepārdēvē. Pēc izmaiņas izpildi go run ./app/backend/tools/apidoc, lai pārrakstītu API maršrutus.

Metadatu servera izsaukumi

HolyArrs nosaukumus, attēlus un ID ņem no HolyArrs metadatu servera. Instalāciju var pārslēgt uz citu serveri ar HOLYARRS_METADATA_URL. Servera kods nav šajā repozitorijā.

Reģistrācija. Pirmajā meklēšanā instalācija izsauc POST /v1/installations bez satura. Atbilde ir 201 ar {"schema_version":1,"token":"hai_..."}. Lietotne saglabā token šifrētu un katrā meklēšanā sūta Authorization: Bearer <token>. Tā reģistrējas vienu reizi. Pēc 401 tā atkārtoti nereģistrējas, tāpēc atsaukta instalācija paliek atsaukta. Ja ir pārsniegts stundas limits adrešu grupai, atbilde ir 429 registration_limit ar Retry-After.

Meklēšana (visas GET)	Maršruts
Meklēšana	/v1/search?provider=tmdb&kind=movie&q=Example&page=1
Filma	/v1/movies/tmdb/{id}
Seriāls	/v1/shows/{tmdb or tvmaze}/{id}
Sezona	/v1/shows/tmdb/{id}/seasons/{n} (sezona 0 ir speciālās epizodes)
Mūzika	/v1/music/musicbrainz/{artist, release-group, release or recording}/{id}

Nezināmi vai atkārtoti parametri tiek noraidīti. Viena nodrošinātāja ID nekad netiek izmantoti citam.

Laba atbilde satur schema_version, source, source_id, fetched_at, expires_at, completeness, stale un data. Apkopojumos HTML uzskati par vienkāršu tekstu.

Statuss	Nozīme
400	Slikts vaicājums, neatkārto
401	Slikts vai atsaukts token, neatkārto
404	Šāda ieraksta nav
429	Pārāk daudz izsaukumu, gaidi Retry-After
503	Aizņemts, pagaidi un mēģini vienu reizi vēlreiz

Saistītais

• API maršruti
• Old-app API
• Vides mainīgie