Ang API ng HolyArrs

Tawagin mula sa sarili mong mga script ang parehong JSON API na ginagamit ng web app, sa ilalim ng /api/v1.

Gawin ang una mong tawag

1. Buksan ang Settings > API > API keys (mga API key) at gumawa ng key na may mga scope lang na kailangan nito. Kopyahin agad, dahil isang beses lang ito ipinapakita.
2. Ipadala ito sa X-Api-Key header sa bawat tawag. Huwag itong ilagay sa address.
3. Tawagin ang base address na http://your-server:6262/api/v1. Kung ang URL base ay /holyarrs, tawagin ang 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"

Dapat may bumalik na JSON. Ang mga error ay {"error": "plain words"} kasama ang HTTP status. Naka-mask ang mga secret na bumabalik.

Mga pagpipilian

Pumili ng scope

Scope	Pinapayagan
health_read	Ang health feed lang, para sa mga monitoring tool
read	Ang mga read route, kasama ang health feed
write	Mga pagbabago, maliban sa mga admin route at control
admin	Mga tao, invite, ask limit, API key, password at two-factor, sign-in settings, restore
control	Mga switch ng Bahagi, yugto, naka-link na app, restart at shutdown
all	read, write at admin. Hindi kasama ang control

Bigyan ng health_read ang monitoring tool at wala nang iba.

Maghanap ng route

Ipinapakita ng Settings > API ang base address, ang mga scope, mga halimbawang tawag, at bawat route kasama ang scope at permiso nito. Nasa /api/v1/openapi.json ang OpenAPI file kapag naka-sign in ka. Nakalista sa Mga API route ang bawat route.

Makipag-usap sa HolyArrs bilang naunang app

Hindi ginagamit ng Seerr, Overseerr, Bazarr at mga katulad na app ang API na ito. Nakikipag-usap sila sa HolyArrs na parang Sonarr at Radarr, na may sarili nilang mga key. Tingnan ang Old-app API.

Kung hindi gumana

Sintomas. 401 sa bawat tawag. Dahilan. Mali o nabura ang key. Solusyon. Gumawa ng bagong key.

Sintomas. 403 sa isang route. Dahilan. Hindi sakop ng scope ng key ang route na iyon. Solusyon. Tingnan ang scope ng route sa Settings > API.

Sintomas. 404 sa bawat tawag. Dahilan. Kulang ang URL base. Solusyon. Ilagay ito bago ang /api/v1. Tingnan ang URL base.

Para sa mga eksperto

Magdagdag ng route

Nasa routes.go ng bawat module ang mga route. Bawat isa ay nirerehistro kasama ang method, path at permiso nito, kaya may permission check ang bawat route.

Galing sa mga route ang openapi.json. Pumapalya ang TestOpenAPIGenerated kapag hindi na sila magkatugma, kaya i-update ito sa parehong pagbabago. Pumapalya rin ang isang route-table snapshot kapag may route na idinagdag, inalis o inilipat nang hindi ina-update ang snapshot.

Kapag nai-release na, mananatili ang mga path at pangalan ng field. Magdagdag ng mga field, huwag palitan ang pangalan. Pagkatapos ng pagbabago, patakbuhin ang go run ./app/backend/tools/apidoc para isulat muli ang Mga API route.

Mga tawag sa metadata server

Kinukuha ng HolyArrs ang mga pangalan, larawan at id mula sa metadata server ng HolyArrs. Ituro ang isang install sa ibang server gamit ang HOLYARRS_METADATA_URL. Wala sa repo na ito ang code ng server.

Registration. Sa unang lookup nito, tumatawag ang isang install sa POST /v1/installations na walang body. Ang sagot ay 201 na may {"schema_version":1,"token":"hai_..."}. Sine-save ng app ang token na naka-encrypt at nagpapadala ng Authorization: Bearer <token> sa bawat lookup. Isang beses lang itong nagpaparehistro. Pagkatapos ng 401, hindi na ito magpaparehistro ulit, kaya nananatiling bawal ang na-revoke na install. Kapag lampas sa oras-oras na limitasyon bawat address group, ang sagot ay 429 registration_limit kasama ang Retry-After.

Lookup (lahat GET)	Route
Search	/v1/search?provider=tmdb&kind=movie&q=Example&page=1
Movie	/v1/movies/tmdb/{id}
Show	/v1/shows/{tmdb or tvmaze}/{id}
Season	/v1/shows/tmdb/{id}/seasons/{n} (ang season 0 ay mga special)
Music	/v1/music/musicbrainz/{artist, release-group, release or recording}/{id}

Tinatanggihan ang mga hindi kilala o inulit na parameter. Ang mga id mula sa isang provider ay hindi kailanman ginagamit para sa iba.

Ang magandang sagot ay may schema_version, source, source_id, fetched_at, expires_at, completeness, stale at data. Ituring na plain text ang HTML sa mga summary.

Status	Ibig sabihin
400	Maling query, huwag nang ulitin
401	Mali o na-revoke na token, huwag nang ulitin
404	Walang ganoong record
429	Sobrang daming tawag, hintayin ang Retry-After
503	Abala, maghintay at ulitin nang isang beses

Kaugnay

• Mga API route
• Old-app API
• Environment variables