A HolyArrs API

Hívd a webes app által is használt JSON API-t a /api/v1 alatt, a saját scriptjeidből.

Az első hívás

1. Nyisd meg a Settings > API > API keys (Beállítások > API > API-kulcsok) oldalt, és készíts egy kulcsot csak a szükséges hatókörökkel. Másold ki most, mert csak egyszer látszik.
2. Küldd el az X-Api-Key fejlécben minden híváskor. Soha ne írd a címbe.
3. Az alapcím http://your-server:6262/api/v1. /holyarrs URL base esetén a cím 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 választ kell kapnod. A hibák {"error": "plain words"} alakúak, HTTP státusszal. A titkok maszkolva jönnek vissza.

Lehetőségek

Válassz hatókört

Hatókör	Engedélyezi
health_read	Csak a működésiállapot-feedet, monitorozó eszközöknek
read	Az olvasó útvonalakat, a működésiállapot-feeddel együtt
write	A módosításokat, kivéve az admin útvonalakat és a vezérlést
admin	Felhasználók, meghívók, kérési korlátok, API-kulcsok, jelszavak és kétfaktoros bejelentkezés, bejelentkezési beállítások, visszaállítás
control	A részek kapcsolói, szakaszok, összekapcsolt appok, újraindítás és leállítás
all	A read, write és admin. A control nem tartozik bele

Egy monitorozó eszköznek health_read-et adj, mást ne.

Útvonal keresése

A Settings > API oldal mutatja az alapcímet, a hatóköröket, példahívásokat, és minden útvonalat a hatókörével és jogosultságával. Az OpenAPI fájl a /api/v1/openapi.json címen érhető el, ha be vagy jelentkezve. Az API-útvonalak oldal minden útvonalat felsorol.

Beszélj a HolyArrs-szal korábbi appként

A Seerr, az Overseerr, a Bazarr és a hasonló appok nem ezt az API-t használják. Úgy beszélnek a HolyArrs-szal, mintha az Sonarr és Radarr lenne, saját kulcsokkal. Lásd: A korábbi appok API-ja.

Ha nem működik

Tünet. 401 minden hívásnál. Ok. A kulcs hibás vagy törölve lett. Megoldás. Készíts új kulcsot.

Tünet. 403 egy útvonalnál. Ok. A kulcs hatóköre nem fedi le az útvonalat. Megoldás. Nézd meg az útvonal hatókörét a Settings > API oldalon.

Tünet. 404 minden hívásnál. Ok. Hiányzik az URL base. Megoldás. Írd a /api/v1 elé. Lásd: URL base.

Haladóknak

Útvonal hozzáadása

Az útvonalak az egyes modulok routes.go fájljában vannak. Mindegyiket a metódusával, útvonalával és jogosultságával regisztrálod, így minden útvonalon van jogosultság-ellenőrzés.

Az openapi.json az útvonalakból készül. A TestOpenAPIGenerated elbukik, ha eltérnek, ezért ugyanabban a változtatásban frissítsd. Az útvonaltábla-snapshot is elbukik, ha egy útvonalat snapshot-frissítés nélkül adsz hozzá, távolítasz el vagy helyezel át.

Kiadás után az útvonalak és a mezőnevek maradnak. Mezőt adj hozzá, de soha ne nevezz át egyet sem. Változtatás után futtasd a go run ./app/backend/tools/apidoc parancsot, hogy újraíródjon az API-útvonalak oldal.

Metaadat-szerver hívások

A HolyArrs a neveket, képeket és azonosítókat a HolyArrs metaadat-szerverétől kapja. Egy telepítést másik szerverre a HOLYARRS_METADATA_URL állít. A szerver kódja nincs ebben a repóban.

Regisztráció. Az első lekérdezésnél a telepítés törzs nélkül hívja a POST /v1/installations útvonalat. A válasz 201, ezzel: {"schema_version":1,"token":"hai_..."}. Az app titkosítva tárolja a tokent, és minden lekérdezésnél elküldi: Authorization: Bearer <token>. Csak egyszer regisztrál. 401 után nem regisztrál újra, így a visszavont telepítés visszavont marad. Ha egy címcsoport átlépi az óránkénti korlátot, a válasz 429 registration_limit, Retry-After fejléccel.

Lekérdezés (mind GET)	Útvonal
Keresés	/v1/search?provider=tmdb&kind=movie&q=Example&page=1
Film	/v1/movies/tmdb/{id}
Sorozat	/v1/shows/{tmdb or tvmaze}/{id}
Évad	/v1/shows/tmdb/{id}/seasons/{n} (a 0. évad a különleges epizódok)
Zene	/v1/music/musicbrainz/{artist, release-group, release or recording}/{id}

Az ismeretlen vagy ismételt paramétereket a szerver elutasítja. Az egyik szolgáltató azonosítóit soha nem használja másikhoz.

Egy jó válaszban ott van a schema_version, source, source_id, fetched_at, expires_at, completeness, stale és data. Az összefoglalókban lévő HTML-t kezeld sima szövegként.

Státusz	Jelentése
400	Hibás lekérdezés, ne próbáld újra
401	Hibás vagy visszavont token, ne próbáld újra
404	Nincs ilyen rekord
429	Túl sok hívás, várd meg a Retry-After időt
503	Elfoglalt, várj, és próbáld újra egyszer

Kapcsolódó oldalak

• API-útvonalak
• A korábbi appok API-ja
• Környezeti változók