HolyArrs API

Iš savo skriptų kviesk tą patį JSON API, kurį naudoja žiniatinklio programa, adresu /api/v1.

Pirmas kreipinys

1. Atidaryk Settings > API > API keys (nustatymai > API > API raktai) ir sukurk raktą tik su tomis apimtimis, kurių jam reikia. Nukopijuok jį iškart, nes jis parodomas tik vieną kartą.
2. Siųsk jį antraštėje X-Api-Key kiekvienu kreipiniu. Niekada nedėk jo į adresą.
3. Kreipkis į pagrindinį adresą http://your-server:6262/api/v1. Jei URL base yra /holyarrs, kreipkis į 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"

Turėtum gauti JSON atsakymą. Klaidos grįžta kaip {"error": "plain words"} su HTTP būsenos kodu. Slaptos reikšmės grįžta paslėptos.

Pasirinkimai

Pasirink apimtį

Apimtis	Leidžia
health_read	Tik būklės srautą, skirtą stebėjimo įrankiams
read	Skaitymo maršrutus, įskaitant būklės srautą
write	Pakeitimus, išskyrus administravimo maršrutus ir valdymą
admin	Žmones, kvietimus, prašymų limitus, API raktus, slaptažodžius ir dviejų veiksmų patvirtinimą, prisijungimo nustatymus, atkūrimą
control	Dalių jungiklius, etapus, susietas programas, paleidimą iš naujo ir išjungimą
all	read, write ir admin. Be control

Stebėjimo įrankiui duok health_read ir nieko daugiau.

Susirask maršrutą

Settings > API rodo pagrindinį adresą, apimtis, kreipinių pavyzdžius ir kiekvieną maršrutą su jo apimtimi ir teise. OpenAPI failas yra adresu /api/v1/openapi.json, kai esi prisijungęs. API maršrutai išvardija visus maršrutus.

Kalbėk su HolyArrs kaip ankstesnė programa

Seerr, Overseerr, Bazarr ir panašios programos šio API nenaudoja. Jos kalba su HolyArrs taip, tarsi tai būtų Sonarr ir Radarr, su savo raktais. Žr. Ankstesnių programų API.

Jei neveikia

Požymis. 401 kiekvienu kreipiniu. Priežastis. Raktas neteisingas arba ištrintas. Sprendimas. Sukurk naują raktą.

Požymis. 403 viename maršrute. Priežastis. Rakto apimtis to maršruto neapima. Sprendimas. Patikrink maršruto apimtį puslapyje Settings > API.

Požymis. 404 kiekvienu kreipiniu. Priežastis. Trūksta URL base. Sprendimas. Įrašyk jį prieš /api/v1. Žr. URL base.

Pažengusiems

Kaip pridėti maršrutą

Maršrutai yra kiekvieno modulio routes.go faile. Kiekvienas užregistruojamas su savo metodu, keliu ir teise, todėl kiekvienas maršrutas turi teisės patikrą.

openapi.json sugeneruojamas iš maršrutų. TestOpenAPIGenerated nepraeina, kai jie išsiskiria, todėl atnaujink jį tame pačiame pakeitime. Maršrutų lentelės snapshot taip pat nepraeina, kai maršrutas pridedamas, pašalinamas ar perkeliamas neatnaujinus snapshot.

Kai versija išleista, keliai ir laukų pavadinimai nebekeičiami. Laukus pridėk, bet niekada nepervadink. Po pakeitimo paleisk go run ./app/backend/tools/apidoc, kad perrašytum API maršrutus.

Kreipiniai į metaduomenų serverį

HolyArrs pavadinimus, paveikslėlius ir id gauna iš HolyArrs metaduomenų serverio. Kad diegimas naudotų kitą serverį, nustatyk HOLYARRS_METADATA_URL. Serverio kodo šiame repo nėra.

Registracija. Per pirmą paiešką diegimas iškviečia POST /v1/installations be turinio. Atsakymas yra 201 su {"schema_version":1,"token":"hai_..."}. Programa išsaugo tokeną užšifruotą ir kiekvienoje paieškoje siunčia Authorization: Bearer <token>. Ji registruojasi vieną kartą. Gavusi 401, ji neregistruojasi iš naujo, todėl atšauktas diegimas lieka atšauktas. Viršijus valandos limitą adresų grupei, atsakymas yra 429 registration_limit su Retry-After.

Paieška (visos GET)	Maršrutas
Paieška	/v1/search?provider=tmdb&kind=movie&q=Example&page=1
Filmas	/v1/movies/tmdb/{id}
Serialas	/v1/shows/{tmdb or tvmaze}/{id}
Sezonas	/v1/shows/tmdb/{id}/seasons/{n} (sezonas 0 yra specialieji epizodai)
Muzika	/v1/music/musicbrainz/{artist, release-group, release or recording}/{id}

Nežinomi ar pasikartojantys parametrai atmetami. Vieno teikėjo id niekada nenaudojami kitam.

Geras atsakymas turi schema_version, source, source_id, fetched_at, expires_at, completeness, stale ir data. HTML santraukose traktuok kaip paprastą tekstą.

Būsena	Reiškia
400	Bloga užklausa, nekartok
401	Blogas ar atšauktas tokenas, nekartok
404	Tokio įrašo nėra
429	Per daug kreipinių, palauk pagal Retry-After
503	Užimta, palauk ir pabandyk vieną kartą

Susiję puslapiai

• API maršrutai
• Ankstesnių programų API
• Aplinkos kintamieji